Troubleshooting
Diagnose scan failures, unreachable sites, missing results, and billing issues before contacting support.
Updated 2026-08-06
Most VisibleMax issues fall into a small set of causes: the crawler cannot reach your site, a pipeline step times out, an AI provider is temporarily unavailable, or a Free-plan lifetime scan has already been used. This section walks a diagnostic flow so you can recover without guessing.
How a scan runs
Every full scan is orchestrated by Trigger.dev as a durable workflow. The core product path is:
- Crawl — fetch your site, discover pages, extract technical and entity signals
- Analyze — build the visibility report, findings, and score from crawl evidence
- Probe — query supported AI platforms for mention and answer-coverage evidence (runs in parallel with discovery enrichment after the core report unlocks)
Hard failures usually stop at crawl or core analyze. Probe and discovery can soft-fail: the report may finish as partial when some AI providers are skipped or unavailable. Partial results are intentional and usable.
Diagnostic flow
- 1
Confirm the symptom
Is the scan failed, stuck/slow, partial, or missing findings? Note the status badge and any
error_messageon the scan detail page. - 2
Check reachability first
Open your project URL in a private browser window. DNS, SSL, and bot/WAF blocks cause most crawl failures — see Website unreachable.
- 3
Separate Free-plan gates from pipeline errors
Free includes one lifetime completed scan. If you already used it, new starts require Pro — that is an entitlement gate, not a crawl bug.
- 4
Accept partial probe coverage when platforms skip
Missing API keys or provider outages skip platforms gracefully. The rest of the report remains valid — see AI provider unavailable.
- 5
Retry once, then follow recovery
After fixing site or billing issues, run one clean rescan. If it still fails, use the recovery checklist and contact support with evidence.
Browse by problem
Scan failed
Pipeline failures, hard vs soft fails, and how to restart cleanly
Website unreachable
DNS, SSL, firewalls, bot blocking, and crawl timeouts
AI provider unavailable
Skipped platforms, partial probes, and what still works
Slow scans
Normal duration vs stuck runs and Trigger.dev waits
Missing results
Thin crawls, gated Free reports, and empty findings
Subscription issues
Pro Early Adopter entitlements, renewals, and sync
Payment issues
Polar checkout, failed charges, and the customer portal
Common errors
Error messages mapped to next actions
Recovery steps
Standard checklist when work is stuck
Failure categories at a glance
| Symptom | Likely cause | Start here |
|---|---|---|
| Scan status failed early | Unreachable site, SSL/DNS, bot block, timeout | Website unreachable |
| Report partial / some platforms blank | Provider key missing or outage (skip gracefully) | AI provider unavailable |
| Cannot start another scan on Free | Lifetime Free scan already used | Missing results · Subscription |
| Checkout or Pro not unlocking | Polar payment or entitlement sync lag | Payment · Subscription |
When to contact support
- The same scan fails twice after you fixed reachability and waited for retries
- Billing charged but Pro features stay locked for more than a few minutes
- A scan ID shows failed with no actionable error and the site loads publicly
- You need help interpreting a partial report before shipping fixes
FAQ
Should I open a support ticket for every partial scan?
No. Partial is expected when some AI providers are unavailable. Use the report you have; re-probe after providers recover if you need fuller coverage.
Does a failed Free scan count against my lifetime scan?
The Free gate tracks completed scans. A hard failure typically does not consume the lifetime allowance — you can retry after fixing the cause. If you are blocked unexpectedly, contact support with the scan ID.
Who orchestrates long-running work?
Trigger.dev owns durable orchestration (retries, progress, crawl → analyze → probe). The VisibleMax app starts the job and reads domain status for the UI.
Related
Still stuck? Contact support with your project URL and what you already tried.