# 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: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/sdks/troubleshooting/

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:

```bash
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 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](#ad-blockers).                                                                     |
| The request is red: blocked by `Content-Security-Policy`              | Your site's policy does not allow the address.                                                                                                                              | See [Content security policy](#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](#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](https://docs.sypnia.com/sdks/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](https://docs.sypnia.com/reference/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:

```bash
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`

```ts
const nextConfig: NextConfig = {
  async rewrites() {
    return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
  },
};
```

`instrumentation-client.ts`

```ts
init({ endpoint: '/_sy' });
```

**nginx**

`nginx.conf`

```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;
}
```

`src/main.ts`

```ts
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 `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](https://docs.sypnia.com/sdks/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](https://docs.sypnia.com/cloud/support) for Sypnia Cloud and in [Contributing](https://docs.sypnia.com/licensing/contributing) for the open-source engine.
