Troubleshooting

Solutions for the most common issues. Run wcag-audit doctor first — it catches most problems automatically.

License errors

"Invalid license key"

• Check the key format: WCAG-XXXX-XXXX-XXXX-XXXX (4 groups of 4 alphanumeric characters)
• Re-run wcag-audit init and paste the key again
• Verify your key at wcagaudit.io/dashboard

"License expired" or "Subscription inactive"

• Check your subscription status at wcagaudit.io/dashboard
• If your card failed, update payment info in the billing portal

"Machine limit reached"

Your tier limits how many devices can use the license. Free = 1, Hobby = 1, Pro = 1, Business = 3, Enterprise = unlimited.

• Deactivate old devices from the dashboard
• Or upgrade your plan for more device slots

Framework detection

"No framework detected"

The CLI looks for framework config files in the current directory.

• Make sure you're in the project root (where package.json lives)
• Supported: Next.js, Vite + React Router, SvelteKit, Remix v2, Astro
• For unsupported frameworks, use --url to scan the deployed site or --routes with a manual route list

# Fallback: scan deployed site
wcag-audit scan --url http://localhost:3000

# Fallback: manual routes
wcag-audit scan --routes ./routes.txt

Dev server issues

"Dev server failed to start"

• Check that npm run dev works manually
• If your dev command is different, set it in .wcagauditrc:

{
  "devServer": {
    "command": "npm run start",
    "port": 4000,
    "healthCheck": "/"
  }
}

Port conflict

If the default port is in use, specify a different one in .wcagauditrc.

Authentication issues

Browser opens but doesn't capture session

• Make sure you complete the full login flow (don't close the browser early)
• The CLI watches for navigation to a post-login page
• If your app uses SSO/OAuth with redirects, it should still work — just complete the full flow

auth.json doesn't work in CI

• Sessions expire — re-export periodically
• Some apps bind sessions to IP addresses — CI runners have different IPs
• Try using a long-lived API token or service account instead

Scan failures

"Page timed out"

The page took too long to load. Common causes:

• Dev server is slow — wait for initial compilation to finish
• Page makes heavy API calls on load — consider mocking or using --url with a staging server

Missing routes

The CLI only discovers static routes by default. Dynamic routes like /blog/[slug] need sample values:

{
  "dynamicRouteSamples": {
    "/blog/[slug]": ["hello-world"],
    "/users/[id]": ["1"]
  }
}

AI vision issues

"AI vision requires a paid plan"

AI vision review is included on Hobby, Pro, Business, and Enterprise plans. Upgrade at wcagaudit.io/pricing, or use --no-ai to run the rule-based checkers only.

AI review is slow

Each page requires a screenshot and a model call. For large sites, use --no-ai during development and run a full AI scan before shipping.

Still stuck?