> ## Documentation Index
> Fetch the complete documentation index at: https://confidence.spotify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Recordings

> Diagnose SDK setup, capture, connection, and display problems.

## Enable Debug Logs

The Recording SDK does not throw setup failures into your application. Use its state
and debug messages to diagnose a problem.

Pass a logger during initialization:

```typescript theme={null}
const recorder = initSessionRecorder({
  clientSecret: '<your-client-secret>',
  debugLogger: message => console.debug(message),
});
```

You can also enable logging for the current browser tab:

```javascript theme={null}
sessionStorage.setItem('CSR_DEBUG', 'true');
```

Reload the page after you set this value. Remove it when testing is complete:

```javascript theme={null}
sessionStorage.removeItem('CSR_DEBUG');
```

## The Recorder Does Not Start

Check `recorder.isRecording`. If it remains `false`, check these conditions:

* The client secret is valid for the current environment.
* A recording policy exists for the client.
* The policy has an enabled rule for the client-secret environment.
* Required context values and the selected targeting identifier are present.
* Targeting, audience allocation, and per-session sampling select the session.
* Account capacity allows another active recording.

Recording might not start even when SDK setup succeeds. Debug output reports when
Confidence skips the session, but it does not identify the specific exclusion.

## Canvas Content Is Not Shown

At present, Confidence does not support recording or replaying content drawn inside
HTML `<canvas>` elements. Canvas content can include sensitive data
that standard masking controls do not reliably protect.

Other page content remains available, but canvas areas can appear blank or incomplete.

## Check Content Security Policy Settings

The SDK uses a Web Worker. Allow `data:` or `blob:` in the `worker-src` Content
Security Policy directive.

The `connect-src` directive must allow these endpoints:

```text theme={null}
https://recording.confidence.dev
wss://recording-ws.confidence.dev
```

The SDK first uses a `data:` URL. It automatically tries a `blob:` URL if the policy
blocks `data:`.

If your policy blocks both sources, copy the packaged worker to a same-origin URL:

```bash theme={null}
cp node_modules/@spotify-confidence/session-recording/dist/confidence-worker.js public/
```

Then configure `workerUrl`:

```typescript theme={null}
const recorder = initSessionRecorder({
  clientSecret: '<your-client-secret>',
  workerUrl: '/confidence-worker.js',
});
```

Use the worker file from the same SDK version. Deploy a new copy when you update the
SDK package.

## Manual Mode

Use manual mode when consent or application state must control when initialization
starts:

```typescript theme={null}
const recorder = initSessionRecorder({
  clientSecret: '<your-client-secret>',
  mode: 'manual',
});

recorder.start();
```

Manual mode changes when the SDK tries to start recording. Recording rules, sample
rates, and account capacity still apply. `start()` has no effect in automatic mode.
`stop()` is permanent for that recorder instance and is safe to call more than once.

## Custom Data Is Missing

The SDK does not queue tags and measurements while the recorder connects. Call
`tag()` or `measure()` only after `recorder.isRecording` becomes `true`. Enable debug
logging to find invalid keys or values.

See [Custom recording data](/docs/recordings/custom-data) for limits and examples.