debugging-local-replay

Debugging local session replay

When a developer says "local replay isn't working" or "recordings aren't showing up", work through these layers in order. The local replay pipeline has several moving parts and failures are usually silent.

Quick symptom guide

Symptom	Likely cause
No /s calls in Network tab	SDK not recording — triggers, settings, or recorder script issue (Step 1)
/s calls return 200 but no recordings in list	Ingestion pipeline broken — capture-replay, Kafka, or ingestion-sessionreplay (Steps 2-3)
Recordings listed but playback stuck on "Buffering..."	recording-api (port 6741) not running (Step 2)
Recorder script MIME type or CORS error in console	Frontend build stale — need pnpm build + pnpm copy-scripts (Step 1)

The local replay pipeline

Browser SDK  →  /s endpoint (Caddy proxy :8000)
             →  capture-replay (Rust, :3306)
             →  Kafka (session_recording_snapshot_item_events topic)
             →  ingestion-sessionreplay (Node, :6740, PLUGIN_SERVER_MODE=recordings-blob-ingestion-v2)
             →  SeaweedFS (blob storage, :8333)
             →  recording-api (Node, :6741, PLUGIN_SERVER_MODE=recording-api)
             →  Frontend

A break at any point in this chain means no recordings in the UI. The diagnostic approach is to find where the chain breaks.

Step 1 — Is the SDK even trying to record?

Ask the developer to open browser DevTools Network tab and filter for /s.

If no /s calls at all: The SDK isn't attempting to send recording data. Investigate client-side causes:

• Triggers configured in project settings. If URL triggers, event triggers, or linked flag triggers are set up, recording won't start until a trigger fires. This is the most common cause for developers who've been testing trigger features. Check Session replay settings in the local UI (Project settings > Session replay). Remove or adjust triggers to allow recording to start.
• Recording disabled in project settings. Session replay may be toggled off.
• Sample rate set too low. If $replay_sample_rate is < 1.0, sessions may be sampled out.
• SDK not initialized with recording. Check the local app's PostHog initialization — session_recording must not be explicitly disabled.
• Wrong PostHog host. The local app must point to http://localhost:8000 (or wherever the local Caddy proxy is running).
• Ad blocker. Even in local dev, browser extensions can block the recorder script or /s endpoint.
• Recorder script failed to load (MIME type / CORS error). The browser console may show MIME type ('text/html') is not executable for posthog-recorder.js or a CORS error for lazy-recorder.js. This means Django is serving an HTML page (usually the login redirect) instead of the JS file — the static recorder scripts are stale or missing. See recorder script build failure.