Docs

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.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Start here: the checklist
  2. Turn on debug
  3. Look at the request
  4. Read the answer, not only the status
  5. Look in the right place
  6. Self-hosted: ask the engine
  7. Nothing arrives
  8. From a Node server
  9. Origins and CORS
  10. Ad blockers
  11. Content security policy
  12. Source maps do not apply
  13. Duplicate or split sessions
  14. A trace is not joined
  15. A replay is missing
  16. 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.

  1. Turn on debug

    Set debug: true in init (in withSypnia for Next.js) and reload.

    You should see
    In the browser’s console, a line [sypnia] started with 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.
  2. Look at the request

    In the developer tools, tab Network, filter by ingest and click something in your app. Wait 10 seconds.

    You should see
    A POST to …/v1/ingest/events with status 200 and a body like {"accepted": 3, "dropped": 0}.
  3. Read the answer, not only the status

    A 200 can still say that events were dropped: {"accepted": 0, "dropped": 3, "dropped_reasons": {…}}. The reasons are listed below.

  4. Look in the right place

    In Sypnia, choose the environment your app sends. An app that runs on localhost with the quickstart’s snippet sends development, and the lists show production by default. Sessions and numbers are complete within 10 minutes; a new problem appears within 2 minutes.

  5. Self-hosted: ask the engine

    Engine On the machine that runs the engine:

    Terminal
    sypnia doctor
    You should see
    One line for each piece the engine depends on (settings, database, storage, public address, AI provider, webhook, clock), each ok, and all checks passed. A line that says FAIL names the setting to change.

    sypnia doctor checks the engine, not your app. If it passes and events still do not show, the cause is on this page.

Nothing arrives

What you seeCauseWhat to do
No request at all, and [sypnia] off: no projectproject 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 outlocalStorage 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: disabledenabled: false.Check the condition you pass.
No request on some pages onlyThe path is in ignoreRoutes.Remove it from the list.
No console line at allinit 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_CLIENTAn ad blocker or a privacy extension.See Ad blockers.
The request is red: blocked by Content-Security-PolicyYour site’s policy does not allow the address.See Content security policy.
401 unauthorizedThe 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_credentialAn 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_allowedThe project lists allowed origins and this page’s origin is not one of them.See Origins and CORS.
413 payload_too_largeNot from the SDK: it keeps batches far below the limit. A proxy in between is rewriting the body.Check the proxy.
429 rate_limitedOne 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 SypniaWrong environment, wrong project, or less than 10 minutes ago.Step 4 above.
Self-hosted: the request fails with a connection or certificate errorendpoint 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 seeCauseWhat to do
No server_request printed with debug: trueinit 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 failedThe server cannot reach the endpoint: a firewall, a proxy, DNS.curl -i <endpoint>/healthz from the same machine.
Nothing from a serverless functionThe function was frozen before the send.Use wrapFetchHandler, or await flush() before returning.
Only some routesStatic 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:

Terminal
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).

HTTP
Access-Control-Allow-Headers: content-type, authorization, traceparent, x-sypnia-session

3. 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

next.config.ts
const nextConfig: NextConfig = {
  async rewrites() {
    return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
  },
};
instrumentation-client.ts
init({ 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.

DirectiveAddNeeded for
connect-srchttps://ingest.sypnia.comSending events and recordings.
script-srchttps://ingest.sypnia.comThe 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.

CheckHowFix
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.

CauseHow to tellWhat 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 environment values. A trace connects one project and one environment.
  • The server SDK started after the server did. Import ./instrument first.

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_routes or in replay.blockedRoutes.
  • The project reached its replays limit. The session’s timeline says so.
  • replay: false in init.
  • Your token lacks the replay scope: 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.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close