Troubleshooting

Work top-down: confirm events flow first, then session replay. Each symptom lists its causes in order of how often we see them.

Quick checklist

Symptom	Most likely cause	Jump to
No events at all	Wrong API key, ad-blocker, or CSP `connect-src`	No events
Events arrive but no replays	Replay not enabled, or CSP blocks the recorder worker	No replays
Replay listed but won’t play	Chunks expired or storage misconfigured (self-host)	Won’t play

No events arriving

Open DevTools → Network, filter for ingest.trackcrumb.com, and reload:

No requests at all — the SDK isn’t initializing. Check that TrackCrumb.init({...}) runs (snippet pasted in <head>, no JS error before it) and that no consent manager is suppressing it.
Requests blocked / (blocked:csp) — add https://ingest.trackcrumb.com to your connect-src CSP directive (see CSP requirements).
Requests show 401 — wrong or revoked API key. Copy a fresh key from Settings → API Keys (st_live_... for production).
Requests never appear, console shows ERR_BLOCKED_BY_CLIENT — an ad-blocker or privacy extension. Test in a clean incognito window; for production traffic consider a first-party proxy.

Events arrive but no session replays

Replay is off by default. It records only when you opt in:

TrackCrumb.init({
  apiKey: "st_live_...",
  apiHost: "https://ingest.trackcrumb.com",
  replayEnabled: true,            // start recording at init, or call
});                               // TrackCrumb.startReplay() later

If replay is enabled and you still see nothing, check DevTools → Console for these errors:

“Refused to create a worker from ‘blob:…’”

Refused to create a worker from 'blob:https://yoursite.com/...' because it
violates the following Content Security Policy directive: "script-src ...".
Note that 'worker-src' was not explicitly set, so 'script-src' is used as
a fallback.

The recorder compresses replay data in a blob: web worker. If your site sets a CSP without a worker-src directive, browsers fall back to script-src, refuse the worker, and replay dies silently — events still flow, so everything looks fine. Add:

worker-src 'self' blob:

This is the single most common cause of “events but no replays”.

”Failed to load …/replay.min.js” or a 404 on `replay.min.js`

The recorder ships as a separate lazy-loaded bundle. When the SDK is loaded through an async loader or bundler, it can’t auto-derive the bundle location and falls back to your page origin — where the file doesn’t exist. Point it at the CDN explicitly:

TrackCrumb.init({
  // ...
  replayEnabled: true,
  replayBundleBaseUrl: "https://cdn.trackcrumb.com/sdk/v1",
});

Also confirm script-src allows https://cdn.trackcrumb.com.

No errors, still no replays

Consent gating — if you gate init() behind a consent banner, replay only records sessions where the visitor accepted. Sessions before acceptance are never recorded retroactively.
Verify uploads directly — with the page open and replay enabled, DevTools → Network should show POST requests to /ingest/replay returning 202 every few seconds of activity. If they return 503 with {"error":"replay storage not configured"}, the ingest backend has no object storage configured (self-hosted installs: set the S3_* environment variables on the ingest service).

Replay is listed but won’t play

The session row exists but the player errors or shows nothing:

Chunks expired — replay data is retained for 30 days; the session metadata can outlive its chunks.
Self-hosted: storage misconfigured on the read path — the dashboard API streams chunks from the same bucket ingest writes to. A chunk fetch failed error in the API logs means the API service is missing or has different S3_* credentials than ingest.

CSP requirements

The complete set of directives for full SDK functionality (events + replay):

script-src  'self' 'unsafe-inline' https://cdn.trackcrumb.com
worker-src  'self' blob:
connect-src 'self' https://ingest.trackcrumb.com

Use a nonce or hash instead of 'unsafe-inline' if your policy forbids it — only the inline bootstrap stub needs covering.

Still stuck?

Email [email protected] with your site URL and a screenshot of the DevTools Console + Network tab filtered to trackcrumb — those two views diagnose nearly every install issue.

Toolbar From PostHog