Troubleshooting
No sessions arriving? Three questions find almost every cause, in this order.
1. Is the SDK on the page?
Open your site with the browser's developer tools → Network and reload. You should see specto.js load (script tag) and a request to /api/sdk/config.
• specto.js is missing or blocked — some ad and tracker blockers block session-replay scripts. Test in a clean browser profile; for real visitors, the npm package (bundled into your own code) or a self-hosted instance on your own domain avoids most blocking.
• A Content-Security-Policy error in the console — see Content Security Policy.
• /api/sdk/config answers 404 with unknown key — the key is wrong or was rotated; copy it again from Settings → General.
2. Is it recording?
In the console:
Specto.session // undefined → nothing is recording on this page Specto.session?.sessionId // the session being recorded
With the npm package, rec.disabled and rec.reason say why. When nothing records, check in this order:
| Reason | How to tell | What to do |
|---|---|---|
| Do-Not-Track or Global Privacy Control | navigator.globalPrivacyControl | By design these visitors are never recorded. Some browsers (Brave, for example) send GPC by default — test in another one. |
| Opted out | localStorage.getItem('specto-optout') | Specto.optIn(), or clear the site's storage. |
| Consent mode, no consent yet | data-consent="required" and no specto-consent in localStorage | Your banner must call Specto.consent(true) — see Consent banners. |
| Not sampled | reason: 'not-sampled'; a sample rate below 1 in the tag or in Settings → Privacy | Each session is sampled once. Open a new tab to roll again, or raise the rate. |
| Recording switched off | Settings → Privacy, the project's recording switch | Switch it back on. |
3. What does ingest answer?
In Network, open a request to /api/ingest. Errors come back as JSON with a code:
| Status | code | Meaning and fix |
|---|---|---|
| 401 | unauthorized | Unknown publishable key — wrong project, or the key was rotated. Update the snippet. |
| 403 | origin_not_allowed | The page's origin isn't in Settings → General → Allowed origins. It must match exactly: scheme, host and port (https://www.example.com ≠ https://example.com). |
| 403 | recording_disabled | Recording is switched off for the project (Settings → Privacy). |
| 403 | suspended | The organization is suspended — contact support. |
| 429 | quota_exceeded | The monthly sessions of the plan are used up. Sessions already in progress keep recording; upgrade, or turn on overage (Settings → Plan & billing). |
| 429 | rate_limited | More uploads per second than the plan allows. The SDK backs off and retries; if it persists, lower the sample rate or upgrade. |
| 429 | session_limit | One session reached its event limit (250,000 by default). The next session records normally. |
| 413 | payload_too_large | A batch over 2 MB. The SDK keeps batches far smaller, so something in between is usually changing the request. |
| 503 | overloaded | The instance is busy. The SDK retries with backoff — nothing is lost while its buffer lasts. |
| 400 | bad_json, bad_request, bad_session_id | The request was altered on the way (a proxy or firewall rewriting bodies), or a custom integration sends the wrong shape. |
Still nothing in the dashboard?
• Sessions show up after their first upload, a few seconds in. Settings → Install says whether the project has received any.
• Check the project switcher: the snippet's key belongs to one project.
• Retries, rate limits and the 503 backoff can delay a session by up to a minute.
Replays look wrong
• Unstyled pages — stylesheets the recorder can't read (cross-origin without CORS) are loaded again when you watch, so they must still be reachable from your browser.
• Empty boxes — canvas drawings and cross-origin iframes aren't recorded; elements with specto-block are left out on purpose.
Anything else: the SDK reference and the privacy controls cover what is captured and how.