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

# Debug frontend errors with session timelines and replay

> Go from a browser error to its source-mapped stack and the session it happened in, then choose per environment whether Forge records a masked replay.

By the end of this guide you will have gone from a production browser error to the line of your source that threw it, and to a timeline of what that user did first. You will also know whether your environment records a masked replay, and how to switch it on or off.

Forge builds every hosted frontend with source maps and files them privately with the release. So an error from a minified bundle is grouped into an issue and resolved to your own files ([source maps and issues](https://docs.reliantlabs.io/hosting/observability/dashboards-and-alerts.md#frontend-errors-issues-and-source-maps)). Each error also carries the id of the browser session it happened in.

## Before you begin

* A frontend deployed to a hosted environment that declares `observability = forge.Observability {}` ([deploy a static site](https://docs.reliantlabs.io/guides/forge/deploy-static-site-cdn.md)). The browser telemetry Forge scaffolds is enough. Sessions exist only for hosted environments.
* `obs:read` in the organization ([credentials](https://docs.reliantlabs.io/hosting/observability/forge-obs.md#credentials)).

The example is a static site whose **Check out** button throws a `TypeError` for a cart with no coupon.

**1. Find the error**

```bash terminal theme={null}
reliant forge obs issues prod
```

```text theme={null}
ISSUE                                 STATUS  EVENTS  AFFECTED    LAST SEEN       SERVICE                      TITLE
384b783c-3ebf-4757-84c8-661206a94552  new     4       4 sessions  11-20 11:25:11  guides-sandbox-sessions-web  TypeError: Cannot read properties of undefined (reading <str>)
```

**2. Read the source-mapped stack**

```bash terminal theme={null}
reliant forge obs issue 384b783c-3ebf-4757-84c8-661206a94552 prod
```

```text theme={null}
384b783c-3ebf-4757-84c8-661206a94552  new  TypeError: Cannot read properties of undefined (reading <str>)
  at src/features/cart.ts in checkoutTotal
  4 events, 4 sessions affected; first 2026-11-20T11:24:01Z (a37e3dcafa23), last 2026-11-20T11:25:11Z (a37e3dcafa23)
  live when last seen: v7.3.0 (promoted 2026-11-20T11:18:53Z)

latest event 2026-11-20T11:25:11Z  trace 69812035e37c1efd2f6a8a4ed52617af
  Cannot read properties of undefined (reading 'percent')

frames:
  checkoutTotal  src/features/cart.ts:7
  previousInstance  src/App.tsx:29
  processDispatchQueue  node_modules/react-dom/cjs/react-dom-client.production.js:13793
  …
```

The frames name your source files and lines, not the minified bundle. The hex id in parentheses is the frontend build that reported the error.

**3. Open the session the error happened in**

The issue's latest event carries its session id:

```bash terminal theme={null}
reliant forge obs issue 384b783c-3ebf-4757-84c8-661206a94552 prod --json --fields latest_event.session_id
reliant forge obs session c0222aa09c6f256de963d06588be4b80 prod
```

```text theme={null}
session c0222aa09c6f256de963d06588be4b80  guides-sandbox-sessions-web a37e3dcafa23  anonymous
  2026-11-20T11:25:04Z, 21s: 1 pages, 0 interactions, 1 errors, replay recorded (watch it in the console)
  entry /

+00:00.0  navigate  / (documentLoad)
+00:00.5  event     page_viewed … entry=true route=/ on /
+00:04.2  event     page_viewed … route=/cart on /cart
+00:06.2  error     TypeError: Cannot read properties of undefined (reading <str>) on /cart → issue 384b783c-3ebf-4757-84c8-661206a94552 (fingerprint d9cf6cf6451b89ed)  trace 69812035e37c1efd2f6a8a4ed52617af

suggested:
  forge obs issue 384b783c-3ebf-4757-84c8-661206a94552 prod
  forge obs trace 69812035e37c1efd2f6a8a4ed52617af prod
```

The user landed on `/`, moved to `/cart`, and hit the error two seconds later. Paths have their query string and fragment removed. When a session has a recording, the header says so, and the console's Sessions view plays it. The CLI never prints the recording.

**4. Browse sessions that have a replay**

```bash terminal theme={null}
reliant forge obs sessions prod --has-error
```

```text theme={null}
APP                          STARTED (UTC)   LENGTH  USER  ENTRY  PAGES  CLICKS  ERRORS  REPLAY  SESSION
guides-sandbox-sessions-web  11-20 11:25:04  21s     -     /      1      0       1       replay  c0222aa09c6f256de963d06588be4b80
guides-sandbox-sessions-web  11-20 11:24:41  21s     -     /      1      0       1       replay  4dd37a8386fbf657d0db2b3556987bcb
```

On a hosted environment, this list shows only sessions with a recorded replay. A session without a replay still has a full timeline, so reach it from its issue as in the previous step. Filter with `--user`, `--path` and `--since`, up to 30 days.

**5. Decide whether this environment records replay**

Replay is a per-frontend switch in each environment's KCL, and it reaches the browser as runtime config:

```kcl deploy/kcl/prod/main.k theme={null}
_session_replay = True
_web_frontend = forge.Frontend {
    name = "web"
    # …
    telemetry = forge.BrowserTelemetry {
        replay = _session_replay
        analytics = forge.Analytics {mode = "full"}
    }
}
```

A recording starts only when all of these are true: `replay` is on, the analytics mode is `full`, your app has called `grantAnalyticsConsent()` from `@reliantlabs/forge-web-runtime` after your consent manager says yes, the browser sends no Global Privacy Control or Do Not Track signal, and the session falls within `replay_sample_rate`.

> [!WARNING]
>
> New projects scaffold `_session_replay = True` in every environment, and the `forge.BrowserTelemetry` default is `replay = False`. The scaffold records nothing as written, because the default analytics mode is `identified`, and an `identified` app never records a replay. Moving to `full` and granting consent is what starts recording. A site adopted with `--in-place` scaffolds `_session_replay = False`.

Masking happens in the browser and cannot be turned off. All text and every input are masked, canvases are not recorded, media and iframes are blocked, and request bodies and headers are not captured ([what is masked](https://docs.reliantlabs.io/hosting/observability/session-timelines.md#what-is-masked)).

**6. Turn replay off for an environment**

Set `_session_replay = False` in that environment's `main.k`, commit, and cut a new release. Hosted deploys ship only recorded releases. Promoting that release removes `OTEL_REPLAY` from the environment's `config.js`, and the deploy refuses until you acknowledge the change:

```bash terminal theme={null}
reliant forge env build prod --release v7.3.1
reliant forge env deploy prod v7.3.1 --yes
```

```text theme={null}
promote refused (runtime_config_regression): release v7.3.1 would change the runtime config (config.js) that v7.3.0, the release this environment runs, serves:
  StaticSite web: drops 1 key(s): OTEL_REPLAY.
```

```bash terminal theme={null}
reliant forge env deploy prod v7.3.1 --yes --acknowledge-destructive runtime_config_regression --note "turn off session replay in prod"
```

Open tabs keep recording until they reload.

**7. Verify the change**

```bash terminal theme={null}
curl -s https://<your-site>/config.js
reliant forge obs session e69e525853d55e9aef6dd38a07fb9e20 prod
```

```text theme={null}
window.__FORGE_CONFIG__ = {"ANALYTICS_MODE":"full","ENVIRONMENT":"prod","OTEL_ENDPOINT":"/_otel"};

session e69e525853d55e9aef6dd38a07fb9e20  guides-sandbox-sessions-web af1e0507c949  anonymous
  2026-11-20T11:47:46Z, 21s: 1 pages, 0 interactions, 1 errors
```

`OTEL_REPLAY` is gone, and new sessions no longer say "replay recorded". They keep their timeline and their errors, and they drop out of `obs sessions`.

## What this does not do

* Replay never records unmasked, and no setting unmasks or unblocks selected elements. If a frontend shows data that must never appear in a recording, even masked, keep its replay off.
* The CLI does not play replays. It prints timelines, and the console plays recordings.
* A local environment has no sessions. `obs sessions` and `obs session` read hosted environments only.
* Replay records a person. Masking does not replace consent, so describe replay in your privacy notice ([privacy and data](https://docs.reliantlabs.io/help/privacy.md)).

## Troubleshooting

> [accordion] obs sessions lists nothing, but obs issues shows browser errors
>
> The list shows only sessions with a recorded replay, and the scaffold's `identified` analytics mode never records one. Open the session from its issue with `obs issue <id> <env> --json --fields latest_event.session_id`.

> [accordion] promote refused (runtime\_config\_regression)
>
> A release that drops a `config.js` key, such as `OTEL_REPLAY` when you turn replay off, needs `--acknowledge-destructive runtime_config_regression --note "<why>"`. The reason is recorded on the promotion.

## Next steps

> [card] [Find the release that caused an error](https://docs.reliantlabs.io/guides/observability/find-release-that-caused-error.md)
>
> Tie the issue to the release and commits that introduced it.

> [card] [Route alerts to Slack, PagerDuty or email](https://docs.reliantlabs.io/guides/observability/route-alerts-slack-pagerduty.md)
>
> Get the `NewIssue` alert for a new frontend error where your team works.

> [card] [Session timelines and replay](https://docs.reliantlabs.io/hosting/observability/session-timelines.md)
>
> Every timeline entry, the JSON schemas, retention and cost.

> [card] [Debug production with an AI agent](https://docs.reliantlabs.io/guides/observability/debug-production-with-ai-agent.md)
>
> Hand the same timelines and issues to an agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.