---
title: Error-session replay
description: Turn on masked error-session replay, choose its sample rate and masking, and understand when a recording exists and why one is missing.
updated: '2026-10-06'
slug: replay
---

# Error-session replay

Error-session replay shows what the shopper's page looked like around an error. It is an optional
module: off until a store owner turns it on, and recorded only in sessions where an error happens.
Sessions without an error upload nothing.

## Turn it on

Open **Settings → Session replay** and choose:

- **Sample rate:** the share of sessions that keep a rolling recording buffer. Start at 100% on a
  small store; lower it on a busy one.
- **Masking:** **Mask all text and inputs** (recommended) shows layout and interactions only.
  **Mask inputs only** keeps page text such as product names and prices visible. Form fields are
  always masked.

The recorder is a separate script, `replay-v1.js`, that loads only when replay is on, the session is
sampled and the visitor allowed analytics. It never runs in cookieless mode.

## What is recorded

1. The recorder keeps the **last minute** of masked page reconstruction in the shopper's browser.
   Nothing leaves the browser while there is no error.
2. When a storefront error happens, it uploads that minute and keeps recording the rest of the
   session until the shopper is idle for 5 minutes, for up to 30 minutes.
3. When a recording ends, the recorder goes back to buffering. A later error in the same session
   starts a new recording.

Each browser tab records its own replay. Failed uploads are retried up to three times. Recording
stops for the rest of a page or session when the collector rate-limits the store or the page changes
its DOM so fast that recording would slow it down, and the replay says so.

## Watch a replay

- From an **issue**, the recommended occurrence is one with a replay when one exists. Playback opens
  **10 seconds before the error**, with the error marked on the timeline.
- From **Sessions**, a **Replay** badge marks sessions with a recording, and the **Has a replay**
  filter lists only those.
- A **session's detail** names the issues its replay recorded.

An error is linked to a replay when it happened inside the recording window, so every error during a
recorded stretch has its replay, not just the first few.

## Why an occurrence has no replay

The issue page states the reason instead of an empty player:

| Reason | What it means |
| --- | --- |
| Replay was off | The store had not turned replay on at the time. Owners get a link to Settings. |
| Outside the sample rate | The session was not sampled. Raise the rate for more coverage. |
| Visitor did not allow analytics | Nothing was recorded, by design. |
| The recording had ended | The session's recording stopped: rate limit or DOM mutation flood. |
| The recording did not reach us | The upload failed after retries, or the tab closed first. |
| Kept 30 days | The replay was older than the retention period. |
| Older storefront script | The error was captured before the store's script reported replay state. |

## Check replay reach

The replay settings panel shows the last seven days: sessions that allowed analytics, cookieless
sessions, consented sessions with an error, those with a replay, and those whose recorder ran but
left no replay. Use it to see why a store has few replays. Consent is usually the largest factor.

## Retention and privacy

Replays are stored privately for 30 days and deleted with the store's data. Inputs are always
masked. See [Privacy and data collection](/docs/privacy-and-data) for the full boundary.