replay: wait for new config before recording decision

Kim Dugan · Kim Dugan · commit 91f0965b674a · 2026-02-20T16:42:52.000-08:00
diff --git a/.changeset/tiny-glasses-pump.md b/.changeset/tiny-glasses-pump.md
@@ -0,0 +1,5 @@
+---
+'posthog-js': patch
+---
+
+wait for fresh config before recording start decision
diff --git a/packages/browser/playwright/mocked/session-recording/lazy-session-recording-sampling.spec.ts b/packages/browser/playwright/mocked/session-recording/lazy-session-recording-sampling.spec.ts
@@ -1,5 +1,5 @@
 import { expect, test, WindowWithPostHog } from '../utils/posthog-playwright-test-base'
-import { start } from '../utils/setup'
+import { start, waitForSessionRecordingToStart } from '../utils/setup'
 
 const startOptions = {
     options: {
@@ -34,6 +34,7 @@ test.describe('Session recording - sampling', () => {
                 await start(startOptions, page, context)
             },
         })
+        await waitForSessionRecordingToStart(page)
 
         await page.expectCapturedEventsToBe(['$pageview'])
         await page.resetCapturedEvents()
diff --git a/packages/browser/playwright/mocked/session-recording/lazy-session-recording.spec.ts b/packages/browser/playwright/mocked/session-recording/lazy-session-recording.spec.ts
@@ -1,5 +1,5 @@
 import { expect, test, WindowWithPostHog } from '../utils/posthog-playwright-test-base'
-import { start } from '../utils/setup'
+import { start, waitForSessionRecordingToStart } from '../utils/setup'
 import { Page } from '@playwright/test'
 import { isUndefined } from '@posthog/core'
 
@@ -99,6 +99,7 @@ test.describe('Session recording - array.js', () => {
                 await start(startOptions, page, context)
             },
         })
+        await waitForSessionRecordingToStart(page)
         await page.expectCapturedEventsToBe(['$pageview'])
         await page.resetCapturedEvents()
     })
diff --git a/packages/browser/playwright/mocked/session-recording/session-linking.spec.ts b/packages/browser/playwright/mocked/session-recording/session-linking.spec.ts
@@ -1,5 +1,5 @@
 import { expect, test, WindowWithPostHog } from '../utils/posthog-playwright-test-base'
-import { start } from '../utils/setup'
+import { start, waitForSessionRecordingToStart } from '../utils/setup'
 
 const startOptions = {
     options: {
@@ -25,6 +25,7 @@ test.describe('Session Recording - Session Linking', () => {
                 await start(startOptions, page, context)
             },
         })
+        await waitForSessionRecordingToStart(page)
         await page.expectCapturedEventsToBe(['$pageview'])
         await page.resetCapturedEvents()
     })
diff --git a/packages/browser/playwright/mocked/session-recording/session-recording-idle-timeout.spec.ts b/packages/browser/playwright/mocked/session-recording/session-recording-idle-timeout.spec.ts
@@ -1,5 +1,5 @@
 import { expect, test, WindowWithPostHog } from '../utils/posthog-playwright-test-base'
-import { start } from '../utils/setup'
+import { start, waitForSessionRecordingToStart } from '../utils/setup'
 import { Page } from '@playwright/test'
 
 async function ensureRecordingIsStopped(page: Page) {
@@ -88,6 +88,7 @@ test.describe('Session recording - idle timeout behavior', () => {
                 await start(startOptions, page, context)
             },
         })
+        await waitForSessionRecordingToStart(page)
         await page.expectCapturedEventsToBe(['$pageview'])
         await page.resetCapturedEvents()
     })
diff --git a/packages/browser/playwright/mocked/session-recording/session-recording-network-recorder.spec.ts b/packages/browser/playwright/mocked/session-recording/session-recording-network-recorder.spec.ts
@@ -1,5 +1,5 @@
 import { test, expect } from '../utils/posthog-playwright-test-base'
-import { start } from '../utils/setup'
+import { start, waitForSessionRecordingToStart } from '../utils/setup'
 import { Page } from '@playwright/test'
 
 test.beforeEach(async ({ context }) => {
@@ -90,6 +90,7 @@ test.beforeEach(async ({ context }) => {
                     )
                 },
             })
+            await waitForSessionRecordingToStart(page)
 
             // also wrap after posthog is loaded
             await page.evaluate((isBadlyBehaved) => {
diff --git a/packages/browser/playwright/mocked/session-recording/session-recording-sampling.spec.ts b/packages/browser/playwright/mocked/session-recording/session-recording-sampling.spec.ts
@@ -1,5 +1,5 @@
 import { expect, test, WindowWithPostHog } from '../utils/posthog-playwright-test-base'
-import { start } from '../utils/setup'
+import { start, waitForSessionRecordingToStart } from '../utils/setup'
 
 const startOptions = {
     options: {
@@ -36,6 +36,7 @@ test.describe('Session recording - sampling', () => {
                 await start(startOptions, page, context)
             },
         })
+        await waitForSessionRecordingToStart(page)
 
         await page.expectCapturedEventsToBe(['$pageview'])
         await page.resetCapturedEvents()
diff --git a/packages/browser/playwright/mocked/session-recording/session-recording.spec.ts b/packages/browser/playwright/mocked/session-recording/session-recording.spec.ts
@@ -1,5 +1,5 @@
 import { expect, test, WindowWithPostHog } from '../utils/posthog-playwright-test-base'
-import { start } from '../utils/setup'
+import { start, waitForSessionRecordingToStart } from '../utils/setup'
 import { Page } from '@playwright/test'
 import { isUndefined } from '@posthog/core'
 
@@ -101,6 +101,7 @@ test.describe('Session recording - array.js', () => {
                 await start(startOptions, page, context)
             },
         })
+        await waitForSessionRecordingToStart(page)
         await page.expectCapturedEventsToBe(['$pageview'])
         await page.resetCapturedEvents()
     })
diff --git a/packages/browser/playwright/mocked/utils/setup.ts b/packages/browser/playwright/mocked/utils/setup.ts
@@ -175,3 +175,17 @@ export async function start(
         await flagsMock
     }
 }
+
+/**
+ * Wait for session recording to actually start after remote config is received
+ * This is needed because session recording now waits for fresh remote config before starting
+ */
+export async function waitForSessionRecordingToStart(page: Page, timeout = 5000): Promise<void> {
+    await page.waitForFunction(
+        () => {
+            const ph = (window as any).posthog
+            return ph?.sessionRecording?.started === true
+        },
+        { timeout }
+    )
+}
diff --git a/packages/browser/src/__tests__/extensions/replay/lazy-sessionrecording.test.ts b/packages/browser/src/__tests__/extensions/replay/lazy-sessionrecording.test.ts
@@ -3819,49 +3819,16 @@ describe('Lazy SessionRecording', () => {
         })
     })
 
-    describe('stale config retry on script loaded', () => {
-        const FIVE_MINUTES_IN_MS = 5 * 60 * 1000
-
+    describe('wait for fresh config before starting', () => {
         beforeEach(() => {
             addRRwebToWindow()
         })
 
-        it('requests fresh config when persisted config is stale', () => {
-            posthog.persistence?.register({
-                [SESSION_RECORDING_REMOTE_CONFIG]: {
-                    enabled: true,
-                    endpoint: '/s/',
-                    cache_timestamp: Date.now() - FIVE_MINUTES_IN_MS - 1000,
-                },
-            })
-
-            sessionRecording.startIfEnabledOrStop()
-
-            expect(mockRemoteConfigLoad).toHaveBeenCalledTimes(1)
-            expect(sessionRecording.started).toBe(false)
-        })
-
-        it('does not request fresh config more than once', () => {
-            posthog.persistence?.register({
-                [SESSION_RECORDING_REMOTE_CONFIG]: {
-                    enabled: true,
-                    endpoint: '/s/',
-                    cache_timestamp: Date.now() - FIVE_MINUTES_IN_MS - 1000,
-                },
-            })
-
-            sessionRecording.startIfEnabledOrStop()
-            sessionRecording.startIfEnabledOrStop()
-
-            expect(mockRemoteConfigLoad).toHaveBeenCalledTimes(1)
-        })
-
-        it('starts recording after fresh config arrives', () => {
+        it('does not start recording until fresh config arrives', () => {
             posthog.persistence?.register({
                 [SESSION_RECORDING_REMOTE_CONFIG]: {
                     enabled: true,
                     endpoint: '/s/',
-                    cache_timestamp: Date.now() - FIVE_MINUTES_IN_MS - 1000,
                 },
             })
 
diff --git a/packages/browser/src/__tests__/extensions/replay/sessionRecording-onRemoteConfig.test.ts b/packages/browser/src/__tests__/extensions/replay/sessionRecording-onRemoteConfig.test.ts
@@ -374,5 +374,65 @@ describe('SessionRecording', () => {
             expect(posthog.get_property(SESSION_RECORDING_REMOTE_CONFIG).enabled).toBe(true)
             expect(sessionRecording['_lazyLoadedSessionRecording']['_endpoint']).toEqual('/ses/')
         })
+
+        it('does not start recording before remote config is received', () => {
+            // Set stale config in persistence (simulating cached/CDN config)
+            posthog.persistence?.register({
+                [SESSION_RECORDING_REMOTE_CONFIG]: {
+                    enabled: true,
+                    endpoint: '/s/',
+                    urlTriggers: [],
+                },
+            })
+
+            // Try to start without receiving remote config
+            sessionRecording.startIfEnabledOrStop()
+
+            // Should not have started recording yet
+            expect(loadScriptMock).not.toHaveBeenCalled()
+            expect(sessionRecording.status).toBe('lazy_loading')
+
+            // Now receive remote config
+            sessionRecording.onRemoteConfig(
+                makeFlagsResponse({
+                    sessionRecording: { endpoint: '/s/' },
+                })
+            )
+
+            // Should now start
+            expect(loadScriptMock).toHaveBeenCalled()
+            expect(sessionRecording.status).toBe('active')
+        })
+
+        it('discards buffer on beforeunload if remote config not yet loaded', () => {
+            // Set persistence to simulate config exists
+            posthog.persistence?.register({
+                [SESSION_RECORDING_REMOTE_CONFIG]: {
+                    enabled: true,
+                    endpoint: '/s/',
+                },
+            })
+
+            // Receive config to start recording
+            sessionRecording.onRemoteConfig(
+                makeFlagsResponse({
+                    sessionRecording: { endpoint: '/s/', urlTriggers: [{ url: 'example.com', matching: 'regex' }] },
+                })
+            )
+
+            // Should be buffering (waiting for trigger)
+            expect(sessionRecording.status).toBe('buffering')
+
+            const lazyRecorder = sessionRecording['_lazyLoadedSessionRecording']
+            const clearBufferSpy = jest.spyOn(lazyRecorder as any, '_clearBuffer')
+            const flushBufferSpy = jest.spyOn(lazyRecorder as any, '_flushBuffer')
+
+            // Trigger beforeunload
+            window.dispatchEvent(new Event('beforeunload'))
+
+            // Should have cleared buffer, not flushed it
+            expect(clearBufferSpy).toHaveBeenCalled()
+            expect(flushBufferSpy).not.toHaveBeenCalled()
+        })
     })
 })
diff --git a/packages/browser/src/extensions/replay/external/lazy-loaded-session-recorder.ts b/packages/browser/src/extensions/replay/external/lazy-loaded-session-recorder.ts
@@ -1334,6 +1334,13 @@ export class LazyLoadedSessionRecording implements LazyLoadedSessionRecordingInt
     }
 
     private _onBeforeUnload = (): void => {
+        // If still buffering (waiting for remote config), discard the buffer
+        // Better to lose this data than record incorrectly.
+        if (this.status === BUFFERING) {
+            this._clearBuffer()
+            return
+        }
+
         this._flushBuffer()
     }
 
diff --git a/packages/browser/src/extensions/replay/session-recording.ts b/packages/browser/src/extensions/replay/session-recording.ts
@@ -73,6 +73,11 @@ export class SessionRecording {
     }
 
     startIfEnabledOrStop(startReason?: SessionStartReason) {
+        // Wait for fresh remote config before starting recording
+        if (!this._receivedFlags) {
+            return
+        }
+
         if (this._isRecordingEnabled && this._lazyLoadedSessionRecording?.isStarted) {
             return
         }

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'posthog-js': patch
 +---
++
 +wait for fresh config before recording start decision