This page routes you to the right fix. Find the stage where you ran into trouble, match your symptom, and follow the link to the deep article. Most issues come down to two things: access (letting our crawler, SuperSchemaBot, read your page) or timing (publishing, CDN, and cache delays). If you are not sure which stage you are at, start from the top and work down.
Tip A huge share of problems are solved by allowing the user agent "SuperSchemaBot" in your firewall or bot-protection rules and making sure robots.txt does not disallow it. Full crawler user agent: Mozilla/5.0 (compatible; SuperSchemaBot/1.0; +https://superschema.ai/bot). See the crawler and access reference.
Scan errors #
You ran a Site Scan and it was blocked, found no pages, or timed out. These are almost always access blocks, not a broken site. Your site can load fine in a browser and still block automated readers.
- "Site Security Challenge"
- The page loads in a normal browser, but Cloudflare or another security tool blocked SuperSchema. Fix: allow SuperSchema, lower bot protection for the URL, or try another public page. See scan troubleshooting.
- "Website Access Blocked"
- SuperSchema could read 0 public pages, usually a firewall, Cloudflare rule, or bot-protection setting. Fix: same as above. See scan troubleshooting.
- DNS error, SSL error, connection refused, timeout, redirect loop, page not found
- Connection and page-level errors, each with its own cause and fix. See the full error table in scan troubleshooting.
- Rate limited or "taking longer than expected"
- Free scans are capped (5 per domain per day, among others), and slow sites can exceed the wait window. See the scan limits and timeout sections in scan troubleshooting.
Generation and URL-access errors #
Schema generation reads your live page to build accurate markup. If it cannot read the page, the same access fixes as a blocked scan apply.
- Generation could not read my page
- The page is likely blocked, behind a challenge, or too slow. Allow SuperSchemaBot and confirm the URL is public. See the crawler and access reference.
- The generated schema looks wrong or incomplete
- You can edit any field or regenerate, and run AI refinement to improve it. See schema generation and editing schema.
Verification failures #
You deployed your schema and verification will not confirm it. The status message tells you which check failed. Re-run verification once first, since publishing and CDN caches can lag.
- Verification says "not detected" or "Schema was not found"
- The code is not on the live page yet, or you verified the wrong URL. Confirm you published (not just saved), and view source for "application/ld+json". See verification troubleshooting.
- "SuperSchema can't access this page yet"
- A robots.txt, CDN, firewall, or bot-protection block (including HTTP 401, 403, 429, or a Cloudflare challenge). Allow SuperSchemaBot. See verification troubleshooting.
- "We checked a different page"
- The URL redirected elsewhere, so the schema was not found at the address you entered. Verify the final destination URL. See verification troubleshooting.
- "Schema found, but it is not the current package"
- An older version is deployed. Re-deploy the current package so the live block matches, then verify again. See verification troubleshooting.
- Schema passed but AI-readable files failed
- Usually a short CDN or cache delay on the .md or .txt alternate files, or missing link tags. Wait and re-verify, or re-deploy the current package. See verification troubleshooting.
HubSpot errors #
You are connecting HubSpot or pushing schema to it and something failed. See the HubSpot integration guide for all of these.
- Connection fails with an expired-code error
- HubSpot authorization codes expire about 60 seconds after you approve. Click "Connect HubSpot Account" again and move through the screens without pausing.
- "Domain Not Associated" warning
- The domain you generated schema for is not associated with the connected portal. Reassociate the domain in HubSpot.
- The content matcher cannot find your page
- Matching is by URL, so the generated URL must line up with the content's live URL and domain in HubSpot.
- Connection showing as "Inactive" or a push asks you to reconnect
- Use "Validate" to test the saved connection, or "Reconnect" to re-run the HubSpot approval and restore one-click deploy.
- A push fails with a permissions error, or content is not found
- The connection may lack the right scopes or the content type could not be loaded. See the HubSpot troubleshooting notes.
Plan and entitlement limits #
Something is gated behind your plan or a limit. These are working as intended, not errors.
- A page or monitoring limit blocked me
- Already-monitored pages keep working; the limit only applies to activating new pages. See choosing a monitoring plan and plans at a glance for what each plan includes.
- A feature is not available on my plan
- Some features (SuperSchema Registry listing, longer history, more citation scans) start on higher tiers. See billing and plans and plans at a glance.
Monitoring, citations, and drift #
- Citation scans or bot tracking look empty
- These build up over time and depend on your plan and on scans having run. Confirm your plan and give them time. See citation tracking and bot tracking.
- A monitoring or drift alert is confusing
- Learn what triggered it and how to clear it in understanding drift events and resolving drift events.
Tip Still stuck after following the linked article? Reach out to Support with the exact message you see and the URL involved. The specific wording tells us which check failed and how to help fastest.