Troubleshooting

Audit fails immediately

Symptom: Audit transitions from pending to failed within a few seconds.

Diagnosis steps:

Open the failed audit — the error message is shown beneath the status badge.
If the message is "URL unreachable" or contains a status code (e.g. 403, 404, 500): confirm the URL is publicly accessible. SitePulse audits from cloud workers — the URL must not require authentication, VPN, or IP allowlisting.
If the message is "Lighthouse timeout": the page may be too slow to fully render within 60 seconds. Try auditing a simpler page first.
If the message references the AI provider: check your BYOK configuration (see BYOK) or wait a few minutes and retry — this may be a transient provider error.

Sitemap audit shows 0 URLs processed

Symptom: You submitted a sitemap URL and the audit shows 0 child audits.

Diagnosis steps:

Confirm the sitemap URL returns valid XML (open it in a browser — it should render as an XML document with <url> entries).
Check the sitemap is not gzip-compressed (SitePulse supports plain XML only; some CMS plugins serve .xml.gz).
Confirm the server returns Content-Type: application/xml or text/xml — an HTML 200 with an error page body can fool the URL check.
If the sitemap is a sitemap index (links to sub-sitemaps), SitePulse recursively follows one level of sub-sitemaps. More deeply nested structures may not be fully traversed.

GEO score is unexpectedly low

Symptom: The page has rich content but the GEO score is below 50.

Diagnosis steps:

Open the GEO category in the audit results. Expand each sub-dimension to see which rubric items scored 0.
Schema (25 pts): check for a <script type="application/ld+json"> block in the page source. Missing JSON-LD is the single biggest GEO score reducer.
Citation (10 pts): does the page cite sources with links or inline attribution? AI systems favor pages that reference external authorities.
GEO Lint (10 pts): review the lint rules in the GEO lint section. Common failures: no FAQ schema, no HowTo schema on instructional pages, missing meta description.
See GEO Score for the full rubric and improvement guidance.

Webflow CMS patches not applying

Symptom: You click Apply on a CMS patch and get an error, or the patch shows as "pending" indefinitely.

Diagnosis steps:

Go to Project Settings → Integrations → Webflow and check the connection status. If it shows "Reconnect", re-authorize the connection.
Confirm the Webflow user account associated with the OAuth connection has Editor or Site Administrator role on the Webflow site.
For CMS item patches: confirm the item's Collection field is not set to read-only in Webflow's CMS schema.
For Designer content patches: note that Webflow Designer (static) content cannot be patched via the CMS API — only CMS Collection items are patchable. Manual edits are required for static elements.
See Webflow OAuth for token troubleshooting.

WordPress meta description patch is "manual-only"

Symptom: The CMS Patches tab shows the meta description suggestion but the Apply button is replaced with "Manual only".

Diagnosis: WordPress core REST API does not expose a meta description field. Auto-patching requires one of:

Yoast SEO plugin
Rank Math plugin
All in One SEO plugin

Install one of these plugins and reconnect the WordPress integration. If a supported plugin is detected, the "manual-only" badge will change to "Auto-apply" on the next audit run.

See WordPress MCP Adapter.

Google Search Console data not showing

Symptom: The project overview page shows "Connect GSC" even though you connected it.

Diagnosis steps:

Go to Project Settings → Integrations → Google Search Console and verify the connection shows a green "Connected" state, not "Reconnect".
Confirm the Property name you entered matches Search Console exactly — Domain properties need the sc-domain: prefix (sc-domain:acme-coffee.example). Also confirm it matches your project's domain exactly. A URL-prefix property (https://acme-coffee.example/) will not return data for http:// requests or www variants.
GSC data has a ~48-hour processing delay. If you connected GSC for a new property, wait 2 days before expecting data.
If the token expired (Google password change or access revoke), click Reconnect in Project Settings → Integrations.

Quota exceeded but billing is current

Symptom: You see "Quota exceeded" on audit submission even though you have an active paid subscription.

Diagnosis steps:

Go to Settings → Billing and check your current usage. The usage bars show how much of each limit you have consumed this period.
Quota resets at the start of your billing period — not on a calendar month. Check when your billing period started.
If you recently upgraded plans, the new limits take effect immediately but the quota counter continues from its current value (it resets at your next period start, not at the upgrade moment). If you need an immediate reset, contact support.
See Quotas & Limits.

BYOK key validation fails

Symptom: Clicking "Save & Validate" shows "Invalid key" even though the key looks correct.

Diagnosis steps:

For Anthropic keys: ensure the key starts with sk-ant- and has credits remaining in your Anthropic account (zero-credit keys are rejected by the API).
For OpenAI keys: ensure the key starts with sk- and the associated organization has an active billing setup.
Keys are sent over HTTPS and never logged — the validation is a live API call. If your API provider is experiencing downtime, validation may fail transiently. Try again after a few minutes.

Search returns no results

Symptom: Typing in the Cmd+K search palette returns "No results".

Diagnosis: The search index (/docs-search-index.json) is built during next build. In development mode, the search palette falls back to navigation-title matching only (not full-text search). If you see no results in production, the search index may not have been built — run npm run docs:search-index and rebuild.

Still stuck?

If none of the above resolves your issue, file a bug report at the SitePulse GitHub Issues page (use the web-auditor label) or email support from your account settings page.