---
title: Verify Browser Session Replay capture
description: "Trace a browser replay through each stage: whether the SDK selected the session, what it recorded and masked, what it uploaded, and whether Amplitude matched the replay to the user's events."
product: session-replay
lang: en
last_updated: 2026-11-18
token_estimate: 2363
---
# Verify Browser Session Replay capture

A replay passes through five stages between the page and Amplitude. Check them in order. The first stage that looks wrong is where the problem is. For changes in each release, go to the [Session Replay Browser SDK release notes](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk-release-notes).

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

| Stage | Question | Where to look |
| --- | --- | --- |
| Sampled | Did the SDK select this session for recording? | [Check whether the session was selected](#check-whether-the-session-was-selected) |
| Captured | Is the SDK recording the page? | [Check what the SDK captured](#check-what-the-sdk-captured) |
| Masked | Does the recording hide what it should? | [Check what the SDK masked](#check-what-the-sdk-masked) |
| Uploaded | Did the upload reach Amplitude? | [Check what the SDK sent](#check-what-the-sdk-sent) |
| Matched | Does the replay open from the user's events? | [Check that the replay matches its session](#check-that-the-replay-matches-its-session) |

For playback problems after a replay arrives, such as missing styles or a replay that's temporarily unavailable, go to [Troubleshoot Session Replay](https://amplitude.com/docs/session-replay/troubleshooting).

## Turn on debug logging

The SDK explains each decision in its debug log. Turn it on in a test environment, and turn it off before you release.

#### Plugin

The plugin uses the Browser SDK 2 log level.

```ts
amplitude.add(sessionReplayPlugin({ sampleRate: 1 }));
amplitude.init("AMPLITUDE_API_KEY", {
  logLevel: amplitude.Types.LogLevel.Debug,
});
```

#### Standalone

The standalone SDK logs almost nothing about recording unless you set `logLevel`. The debug level is `4`.

```ts
await sessionReplay.init("AMPLITUDE_API_KEY", {
  deviceId: "device-abc123",
  sessionId: 1735689600000,
  sampleRate: 1,
  logLevel: 4,
}).promise;
```

Messages appear in the browser console with the prefix `Amplitude Logger [Log]:`, `Amplitude Logger [Debug]:`, or, for upload failures, `Amplitude Logger [Warn]:`.

## Check whether the session was selected

The SDK records a session only when all of these conditions are true. The SDK checks them in this order:

1. `init()` has run and has a session ID and a device ID.
2. Your code hasn't stopped recording with `stop()` or `shutdown()`.
3. The SDK loaded its remote configuration, and capture is on for the project.
4. The user isn't opted out.
5. The session matches [targeting](https://amplitude.com/docs/session-replay/targeted-replay-capture) if the project uses it. Otherwise, the sample rate selects it.

The debug log names the check that failed:

| Debug log message | Meaning |
| --- | --- |
| `Session Replay capture beginning for <session ID>.` | The session is selected and recording. |
| `Opting session <session ID> out of recording due to sample rate.` | The sample rate didn't select this session. A rate of `0` selects none. |
| `Session <session ID> not being captured due to capture being disabled for project or because the remote config could not be fetched.` | The remote configuration request failed or timed out, or capture is off in [Session Replay settings](https://amplitude.com/docs/session-replay/session-replay-settings). |
| `Opting session <session ID> out of recording due to optOut config.` | The user is opted out. |
| `Not capturing replays for session <session ID> due to not matching targeting conditions.` | Targeted capture is on, and the session hasn't matched its conditions yet. |
| `Session is not being recorded due to lack of session id.` or `... lack of device id.` | Standalone only. `init()` didn't receive the ID. |
| `Session <session ID> not being captured because recording was stopped.` | Your code called `stop()` or `shutdown()`. |

The sample rate in [Session Replay settings](https://amplitude.com/docs/session-replay/configure-sampling) overrides `sampleRate` in code. The SDK selects a session from a hash of its session ID, so every page and tab that shares a session ID gets the same result.

## Check what the SDK captured

Read the replay properties from the SDK.

#### Plugin

Keep a reference to the plugin, and call its method:

```ts
const sessionReplayTracking = sessionReplayPlugin({ sampleRate: 1 });
amplitude.add(sessionReplayTracking);
amplitude.init("AMPLITUDE_API_KEY");

// After init finishes:
console.log(sessionReplayTracking.getSessionReplayProperties());
// { "[Amplitude] Session Replay ID": "<device ID>/<session ID>" }
```

#### Standalone

```ts
console.log(sessionReplay.getSessionReplayProperties());
// { "[Amplitude] Session Replay ID": "device-abc123/1735689600000" }
```

An empty object, `{}`, means the session isn't recording. Go back to [Check whether the session was selected](#check-whether-the-session-was-selected).

Some content never appears in a replay, even when recording works. For the list, go to [Known limitations](https://amplitude.com/docs/sdks/session-replay/browser/instrument-and-configure#known-limitations).

## Check what the SDK masked

By default, Session Replay masks the text of every input field and records other page text. Check masking in a test replay before you record real users:

1. Record a test session on a page that shows the data you need to hide.
2. Open the replay in Amplitude.
3. Confirm that masked text appears as asterisks, and that blocked elements appear as empty placeholders.

Masking happens in the browser, before upload. If the project sets a privacy level in [Session Replay settings](https://amplitude.com/docs/session-replay/manage-privacy-settings-for-session-replay), that level overrides `privacyConfig.defaultMaskLevel` in code. To change what's masked, go to [Mask data](https://amplitude.com/docs/sdks/session-replay/browser/instrument-and-configure#mask-data).

## Check what the SDK sent

Open the browser developer tools, select the **Network** tab, and filter for `sessions`. Interact with the page, because the SDK sends a batch only after it records new activity.

| Request | What to check |
| --- | --- |
| `GET https://sr-client-cfg.amplitude.com/config/<API key>?config_group=browser` | Remote configuration. Must succeed before the SDK records. EU projects use `sr-client-cfg.eu.amplitude.com`. |
| `POST https://api-sr.amplitude.com/sessions/v2/track?device_id=...&session_id=...&type=replay` | Replay data. A `2xx` status means Amplitude accepted the batch. EU projects use `api-sr.eu.amplitude.com`. The `device_id` and `session_id` parameters identify the replay. |

The SDK compresses each upload with gzip and sends `Content-Encoding: gzip`, so the **Payload** tab shows unreadable bytes.

With the standalone SDK, you can set `enableTransportCompression: false` in a test environment to send readable JSON. With debug logging on, each accepted batch also logs `Session replay event batch tracked successfully for session id <session ID>, size of events: <n> KB`. The `X-Client-Library` request header names the variant and version, for example `plugin/1.36.7` or `standalone/1.51.8`.

When the user hides or leaves the page, the SDK sends the last batch with `navigator.sendBeacon`. The beacon request carries the API key in its URL, skips compression, and has a 64 KB limit.

### Read upload errors

The SDK logs these messages when an upload fails:

| Message | Cause |
| --- | --- |
| `Session replay event batch rejected due to exceeded retry count` | The request failed with a network error, a timeout, or a `408`, `429`, `499`, or `5xx` status on every attempt. The SDK retries a batch up to two times. |
| `Network error occurred, event batch rejected` | Amplitude returned another error status, such as `400` or `401`. The SDK doesn't retry these. |
| `Session replay event batch dropped: server signalled capture disabled or session out of valid range for this session` | Amplitude accepted the request but told the SDK to stop sending this session. |
| `Session replay throttled by server; pausing flush schedule for 60s` | Amplitude asked the SDK to slow down. The SDK resumes after 60 seconds. |

For request failures you can't see in the browser, use the [Ingestion Monitor](https://amplitude.com/docs/session-replay/ingestion-monitor).

## Check that the replay matches its session

Amplitude links a replay to the user's events by device ID and session ID. Compare the IDs on both sides:

1. In the **Network** tab, read `device_id` and `session_id` from the replay upload URL.
2. In _User Lookup_, open an event from the same session and read its device ID and session ID.
3. If the IDs differ, fix the source that sends the wrong value. With the standalone SDK, pass the IDs your analytics tool uses, and call `setSessionId()` whenever its session changes.

The plugin also adds `[Amplitude] Session Replay ID`, in the form `<device ID>/<session ID>`, to every Browser SDK 2 event in the session except Identify events. After a replay arrives, Amplitude creates an [`[Amplitude] Replay Captured`](https://amplitude.com/docs/session-replay/replay-captured-event) event for it, which you can find in the user's activity.

If your project uses a custom session definition or doesn't send session IDs, go to [Choose a session matching option](https://amplitude.com/docs/session-replay/session-matching).

