Troubleshooting
What to check when nothing arrives, when requests are blocked by an ad blocker, CORS or a content security policy, when source maps do not apply, and when sessions look duplicated.
On this page
- Start here: the checklist
- Turn on debug
- Look at the request
- Read the answer, not only the status
- Look in the right place
- Self-hosted: ask the engine
- Nothing arrives
- From a Node server
- Origins and CORS
- Ad blockers
- Content security policy
- Source maps do not apply
- Duplicate or split sessions
- A trace is not joined
- A replay is missing
- Still stuck
This page is for when the SDK is installed and something is missing. It covers the three SDKs, for the open-source engine and for Sypnia Cloud; steps that apply to one of them only are marked.
Start here: the checklist
Do these in order. Most cases end at one of the first four.
Turn on debug
Set
debug: trueininit(inwithSypniafor Next.js) and reload.You should seeIn the browser’s console, a line[sypnia] startedwith the project’s key prefix, the endpoint, the environment and the release, then one line for each event. If you see[sypnia] off:it is followed by the reason.Self-hosted: ask the engine
Engine On the machine that runs the engine:
Terminal sypnia doctorYou should seeOne line for each piece the engine depends on (settings, database, storage, public address, AI provider, webhook, clock), eachok, andall checks passed. A line that saysFAILnames the setting to change.sypnia doctorchecks the engine, not your app. If it passes and events still do not show, the cause is on this page.
Nothing arrives
| What you see | Cause | What to do |
|---|---|---|
No request at all, and [sypnia] off: no project | project is empty. Often an environment variable that is not defined in the browser bundle. | Print the value you pass. In Vite the variable must start with VITE_; in Next.js use withSypnia. |
No request at all, and [sypnia] off: opted out | localStorage holds sypnia:off. Someone called optOut(), or a test setup left it. | Call optIn(), or remove the key. |
No request at all, and [sypnia] off: disabled | enabled: false. | Check the condition you pass. |
| No request on some pages only | The path is in ignoreRoutes. | Remove it from the list. |
| No console line at all | init never ran: the file is not imported, or the script tag has no data-project and nothing calls init. | Import the file first in your entry point. |
The request is red: net::ERR_BLOCKED_BY_CLIENT | An ad blocker or a privacy extension. | See Ad blockers. |
The request is red: blocked by Content-Security-Policy | Your site’s policy does not allow the address. | See Content security policy. |
401 unauthorized | The key is unknown or revoked, or it belongs to another engine. | Copy the key again. A Cloud key does not work on a self-hosted engine, nor the reverse. |
403 wrong_credential | An API token (sps_…) or the root token was used as project. | Use the ingest key (spk_…). Revoke the token: it was exposed. |
403 origin_not_allowed | The project lists allowed origins and this page’s origin is not one of them. | See Origins and CORS. |
413 payload_too_large | Not from the SDK: it keeps batches far below the limit. A proxy in between is rewriting the body. | Check the proxy. |
429 rate_limited | One address is sending too fast with this key. | The SDK waits and retries by itself. If it persists, look for a loop that throws or calls track. |
200 with dropped_reasons: { limit_reached: … } | The project reached a limit. | See Sampling and quotas. |
200 with dropped_reasons: { invalid: … } | An event lacks a required field. From an official SDK this is a bug; from your own client, compare with the event schema. | Report it with the event printed by debug. |
200, nothing dropped, nothing in Sypnia | Wrong environment, wrong project, or less than 10 minutes ago. | Step 4 above. |
| Self-hosted: the request fails with a connection or certificate error | endpoint is not the engine’s public base URL, or the engine is not reachable from the internet over HTTPS. | Open <endpoint>/healthz in a browser. Run sypnia doctor --only address. |
From a Node server
| What you see | Cause | What to do |
|---|---|---|
No server_request printed with debug: true | init ran after the server was created, or in another process. | Import ./instrument on the first line of the entry file. |
Events are printed, then send failed | The server cannot reach the endpoint: a firewall, a proxy, DNS. | curl -i <endpoint>/healthz from the same machine. |
| Nothing from a serverless function | The function was frozen before the send. | Use wrapFetchHandler, or await flush() before returning. |
| Only some routes | Static files, OPTIONS and ignoreRoutes are not traced. | That is the default. |
Origins and CORS
Three different things are called CORS problems.
1. Ingest refuses your page’s origin. Ingest answers CORS for every origin by itself; you configure nothing on it. The exception is a project that lists allowed origins (settings.allowed_origins): then other origins get 403 origin_not_allowed. Add the origin, with its scheme and port, or empty the list:
curl -X PATCH "https://api.sypnia.com/v1/projects/shop" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"settings": {"allowed_origins": ["https://shop.example", "http://localhost:5173"]}}'Preview addresses of app builders and hosts change with every deploy. Either leave the list empty, or do not expect previews to report.
2. Your own API refuses the trace headers. If your API is on another origin and is listed in traceTargets, the browser asks it first whether traceparent and x-sypnia-session are allowed. If your API says no, your own calls fail. Allow both headers in the API’s CORS answer, or remove the API from traceTargets (use recordTargets to keep recording its calls without headers).
Access-Control-Allow-Headers: content-type, authorization, traceparent, x-sypnia-session3. A self-hosted engine behind your own proxy. Let the engine answer OPTIONS itself. If the proxy adds its own CORS headers on top of the engine’s, browsers reject the answer because the header appears twice.
Ad blockers
Some ad blockers and privacy extensions block requests to monitoring services by host name. The app keeps working: the SDK fails quietly. You lose the sessions of those visitors.
The fix is to send through your own domain. Add a route to your site that forwards to ingest, and set endpoint to it. A path on the page’s own origin is a valid endpoint.
Next.js
const nextConfig: NextConfig = {
async rewrites() {
return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
},
};init({ endpoint: '/_sy' });nginx
location /_sy/ {
proxy_pass https://ingest.sypnia.com/;
proxy_set_header Host ingest.sypnia.com;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_ssl_server_name on;
}init({ project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e', endpoint: '/_sy' });Keep X-Forwarded-For: rate limits are per address, and without it all your visitors share your proxy’s. With the script tag, serve sdk.js through the same route: src="/_sy/v1/sdk.js" and data-endpoint="/_sy". On a self-hosted engine, forward to your engine’s base URL instead.
A blocker that blocks by the shape of the request rather than the host cannot be worked around, and should not be: that visitor asked not to be measured.
Content security policy
If your site sends a Content-Security-Policy, allow Sypnia in it. Replace the host by your engine’s on a self-hosted engine, or by 'self' if you send through your own domain.
| Directive | Add | Needed for |
|---|---|---|
connect-src | https://ingest.sypnia.com | Sending events and recordings. |
script-src | https://ingest.sypnia.com | The script tag only. Not needed with the npm package. |
The SDK uses no inline script, no eval and no worker.
Source maps do not apply
A stack still shows checkout-3f9c.js:1:48211 instead of src/checkout/checkout.tsx:142.
| Check | How | Fix |
|---|---|---|
| The release on the event is the release you uploaded for. | Open an occurrence of the problem and read its release. Compare with --release in your build. A full commit hash and its first 7 characters are different releases. | Use one expression for both. In Next.js, withSypnia does. |
| The event has a release at all. | debug: true prints release at start. | Pass release to init. |
| The maps arrived. | curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" -H "Authorization: Bearer $SYPNIA_API_TOKEN": each file must say "uploaded": true. | Run the upload again; it skips what is there. |
| The paths match. | In that list, url_path must be the path the browser loads the file from: /assets/checkout-3f9c.js. | Set --url-prefix in sypnia sourcemaps upload. |
| The maps were built. | Your bundler must write .map files: build.sourcemap: 'hidden' in Vite, devtool: 'hidden-source-map' in webpack. | Turn them on, and delete them after the upload. |
| The upload ran before the deploy removed the files. | Read the build log: the upload prints how many maps it found. | Upload right after bundling. |
| The failure is older than the upload. | Maps apply from the problem’s next occurrence. | Wait for the next one, and ask for a new analysis. |
| A map is larger than 64 MB. | The upload lists it as skipped. | Split the bundle. |
| The stack is from the server of a Next.js app. | — | Server source maps are Planned. |
Grouping never depends on source maps: the problem is the same problem before and after.
Duplicate or split sessions
One visit shows as several sessions.
| Cause | How to tell | What to do |
|---|---|---|
| The browser blocks storage (private mode in some browsers, strict settings, an embedded web view without storage). | debug: true prints storage unavailable, session kept in memory. Each full page load is then a new session. | Nothing in the SDK can fix it. A single-page app is not affected, because it does not reload. |
Two origins. shop.example and app.shop.example, or http and https, have separate storage. | The sessions come in pairs with different hosts. | Serve the app from one origin. Sessions cannot be shared across origins at launch. |
| The page is embedded in a frame on another site. | Sessions from the embedding site. | Expected: a frame has its own storage. |
| 30 minutes without activity. | The gap between the two sessions is longer than 30 minutes. | Expected. |
Another person was identified, or identify(null) was called. | The sessions have different persons. | Expected. Do not call identify(null) on every page load before you know who is signed in. |
| The SDK is loaded twice from two different builds. | Two [sypnia] started lines. | The second one does nothing by design: one session. If you see double events, report it. |
| Tests or bots. | Many one-page sessions from the same device class. | Run tests with enabled: false, or localStorage.setItem('sypnia:off', '1'). |
A trace is not joined
The browser’s call and the server’s request show as two traces.
- The API is on another origin and is not in
traceTargets: the header is not sent. Add it. - The API’s CORS does not allow
traceparent: see above. - A proxy or gateway in between removes or replaces
traceparent. Let it pass through. - The browser and the server send to different projects or with different
environmentvalues. A trace connects one project and one environment. - The server SDK started after the server did. Import
./instrumentfirst.
A replay is missing
- The session was not in the sampled share and nothing went wrong in it. That is the default: see Sampling and quotas.
- The session is still active. A replay is watchable once the session has been idle for 2 minutes, or has ended.
- The route is in the project’s
replay.blocked_routesor inreplay.blockedRoutes. - The project reached its replays limit. The session’s timeline says so.
replay: falseininit.- Your token lacks the
replayscope: you see that a replay exists and cannot open it.
Still stuck
Collect these before you ask: the SDK’s name and version, the console output with debug: true from start to the first send, the status and body of the request to ingest, and, on a self-hosted engine, the output of sypnia doctor. Remove the API token if one appears; the ingest key is public. Where to ask is in Support for Sypnia Cloud and in Contributing for the open-source engine.