replay: wait for new config before recording decision

Kim Dugan · Kim Dugan · commit ff3bd622d35b · 2026-02-20T17:05:05.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-array-full.spec.ts b/packages/browser/playwright/mocked/session-recording/session-recording-array-full.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: {
@@ -21,6 +21,7 @@ const startOptions = {
 test.describe('session recording in array.full.js', () => {
     test('captures session events', async ({ page, context }) => {
         await start(startOptions, page, context)
+        await waitForSessionRecordingToStart(page)
 
         await page.waitingForNetworkCausedBy({
             urlPatternsToWaitFor: ['**/ses/*'],
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-linked-flags.spec.ts b/packages/browser/playwright/mocked/session-recording/session-recording-linked-flags.spec.ts
@@ -1,5 +1,5 @@
 import { test, WindowWithPostHog } from '../utils/posthog-playwright-test-base'
-import { start, StartOptions } from '../utils/setup'
+import { start, StartOptions, waitForRemoteConfig } from '../utils/setup'
 import { assertThatRecordingStarted, pollUntilEventCaptured } from '../utils/event-capture-utils'
 import { BrowserContext, Page } from '@playwright/test'
 
@@ -42,6 +42,7 @@ test.describe('Session recording - linked flags', () => {
             page,
             context
         )
+        await waitForRemoteConfig(page)
         await page.expectCapturedEventsToBe(expectedStartingEvents)
         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/session-recording/triggerMatch-type.spec.ts b/packages/browser/playwright/mocked/session-recording/triggerMatch-type.spec.ts
@@ -1,6 +1,6 @@
 import { RemoteConfig } from '@/types'
 import { expect, test, WindowWithPostHog } from '../utils/posthog-playwright-test-base'
-import { start } from '../utils/setup'
+import { start, waitForRemoteConfig } from '../utils/setup'
 import { pollUntilEventCaptured } from '../utils/event-capture-utils'
 
 const startOptions = {
@@ -52,6 +52,7 @@ test.describe('Session recording - trigger match types 0% sampling + event trigg
                     await start(anyMatchOptions, page, context)
                 },
             })
+            await waitForRemoteConfig(page)
             await page.expectCapturedEventsToBe(['$pageview'])
             await page.resetCapturedEvents()
         })
@@ -94,6 +95,7 @@ test.describe('Session recording - trigger match types 0% sampling + event trigg
                     await start(allMatchOptions, page, context)
                 },
             })
+            await waitForRemoteConfig(page)
             await page.expectCapturedEventsToBe(['$pageview'])
             await page.resetCapturedEvents()
         })
@@ -172,6 +174,7 @@ test.describe('Session recording - trigger match types 0% sampling + event trigg
                     await start(anyMatchOptions, page, context)
                 },
             })
+            await waitForRemoteConfig(page)
             await page.expectCapturedEventsToBe(['$pageview'])
             await page.resetCapturedEvents()
         })
@@ -230,6 +233,7 @@ test.describe('Session recording - trigger match types 0% sampling + event trigg
                     await start(allMatchOptions, page, context)
                 },
             })
+            await waitForRemoteConfig(page)
             await page.expectCapturedEventsToBe(['$pageview'])
             await page.resetCapturedEvents()
         })
diff --git a/packages/browser/playwright/mocked/session-recording/urlTrigger-persistence.spec.ts b/packages/browser/playwright/mocked/session-recording/urlTrigger-persistence.spec.ts
@@ -1,6 +1,6 @@
 import { RemoteConfig } from '@/types'
 import { expect, test } from '../utils/posthog-playwright-test-base'
-import { start } from '../utils/setup'
+import { start, waitForRemoteConfig } from '../utils/setup'
 
 test.describe('Session recording - URL trigger with persistence and eager loading disabled', () => {
     // a regression test because we missed this on first switching to lazy loading
@@ -49,6 +49,7 @@ test.describe('Session recording - URL trigger with persistence and eager loadin
                 await start(initialOptions, page, context)
             },
         })
+        await waitForRemoteConfig(page)
 
         // Verify initial pageview is captured
         await page.expectCapturedEventsToBe(['$pageview'])
@@ -87,6 +88,7 @@ test.describe('Session recording - URL trigger with persistence and eager loadin
                     page,
                     page.context()
                 )
+                await waitForRemoteConfig(page)
 
                 await page.resetCapturedEvents()
             },
diff --git a/packages/browser/playwright/mocked/utils/setup.ts b/packages/browser/playwright/mocked/utils/setup.ts
@@ -175,3 +175,33 @@ 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 }
+    )
+}
+
+/**
+ * Wait for remote config to be received and processed
+ * Use this when recording might not start due to triggers/sampling, but you need config to be loaded
+ * After config is received, status changes from 'lazy_loading' to either 'active', 'buffering', or 'disabled'
+ */
+export async function waitForRemoteConfig(page: Page, timeout = 5000): Promise<void> {
+    await page.waitForFunction(
+        () => {
+            const ph = (window as any).posthog
+            const status = ph?.sessionRecording?.status
+            return status !== 'lazy_loading' && status !== undefined
+        },
+        { 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
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`import { test, WindowWithPostHog } from '../utils/posthog-playwright-test-base'`
`2`		`-import { start, StartOptions } from '../utils/setup'`
	`2`	`+import { start, StartOptions, waitForRemoteConfig } from '../utils/setup'`
`3`	`3`	`import { assertThatRecordingStarted, pollUntilEventCaptured } from '../utils/event-capture-utils'`
`4`	`4`	`import { BrowserContext, Page } from '@playwright/test'`
`5`	`5`
`@@ -42,6 +42,7 @@ test.describe('Session recording - linked flags', () => {`
`42`	`42`	`page,`
`43`	`43`	`context`
`44`	`44`	`)`
	`45`	`+ await waitForRemoteConfig(page)`
`45`	`46`	`await page.expectCapturedEventsToBe(expectedStartingEvents)`
`46`	`47`	`await page.resetCapturedEvents()`
`47`	`48`	`}`