Recover lazy chunk failures after frontend deploys

mandar1045 · mandar1045 · commit b64d7504d506 · 2026-05-05T20:55:41.000+05:30
diff --git a/frontend/src/layout/ErrorBoundary/ErrorBoundary.test.tsx b/frontend/src/layout/ErrorBoundary/ErrorBoundary.test.tsx
@@ -0,0 +1,64 @@
+import '@testing-library/jest-dom'
+
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+
+import * as chunkLoadErrorRecovery from 'lib/utils/chunkLoadErrorRecovery'
+
+import { initKeaTests } from '~/test/init'
+
+import { ErrorBoundary } from './ErrorBoundary'
+
+function ThrowChunkLoadError(): never {
+    throw new Error('Failed to fetch dynamically imported module: /static/chunk.js')
+}
+
+describe('ErrorBoundary', () => {
+    let consoleErrorSpy: jest.SpyInstance
+    let reloadAfterChunkLoadErrorSpy: jest.SpyInstance
+
+    beforeEach(() => {
+        initKeaTests()
+        chunkLoadErrorRecovery.clearChunkLoadReloadAttempt()
+        consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined)
+        reloadAfterChunkLoadErrorSpy = jest
+            .spyOn(chunkLoadErrorRecovery, 'reloadAfterChunkLoadError')
+            .mockImplementation(() => undefined)
+    })
+
+    afterEach(() => {
+        cleanup()
+        consoleErrorSpy.mockRestore()
+        reloadAfterChunkLoadErrorSpy.mockRestore()
+    })
+
+    it('reloads once for a chunk load error before showing the generic fallback', async () => {
+        render(
+            <ErrorBoundary>
+                <ThrowChunkLoadError />
+            </ErrorBoundary>
+        )
+
+        expect(await screen.findByText('Refreshing…')).toBeInTheDocument()
+
+        await waitFor(() => {
+            expect(reloadAfterChunkLoadErrorSpy).toHaveBeenCalledTimes(1)
+        })
+
+        expect(screen.queryByText('An error has occurred')).not.toBeInTheDocument()
+    })
+
+    it('shows the network error state after a recent reload attempt', async () => {
+        chunkLoadErrorRecovery.markChunkLoadReloadAttempt()
+
+        render(
+            <ErrorBoundary>
+                <ThrowChunkLoadError />
+            </ErrorBoundary>
+        )
+
+        expect(await screen.findByText('Network error')).toBeInTheDocument()
+        expect(screen.getByText('There was an issue loading the requested resource.')).toBeInTheDocument()
+        expect(reloadAfterChunkLoadErrorSpy).not.toHaveBeenCalled()
+        expect(screen.queryByText('An error has occurred')).not.toBeInTheDocument()
+    })
+})
diff --git a/frontend/src/layout/ErrorBoundary/ErrorBoundary.tsx b/frontend/src/layout/ErrorBoundary/ErrorBoundary.tsx
@@ -2,16 +2,20 @@ import './ErrorBoundary.scss'
 
 import clsx from 'clsx'
 import { useActions, useValues } from 'kea'
+import { useEffect } from 'react'
 
 import { IconCopy } from '@posthog/icons'
 import { PostHogErrorBoundary, type PostHogErrorBoundaryFallbackProps } from '@posthog/react'
 
 import { SupportTicketExceptionEvent, supportLogic } from 'lib/components/Support/supportLogic'
 import { LemonBanner } from 'lib/lemon-ui/LemonBanner'
 import { LemonButton } from 'lib/lemon-ui/LemonButton'
+import { getChunkLoadRecoveryAction, reloadAfterChunkLoadError } from 'lib/utils/chunkLoadErrorRecovery'
 import { copyToClipboard } from 'lib/utils/copyToClipboard'
 import { teamLogic } from 'scenes/teamLogic'
 
+import { ErrorNetwork } from '../ErrorNetwork'
+
 const DOM_MUTATION_PATTERNS = [
     "Failed to execute 'removeChild' on 'Node'",
     "Failed to execute 'insertBefore' on 'Node'",
@@ -29,6 +33,36 @@ interface ErrorBoundaryProps {
     className?: string
 }
 
+function ChunkLoadErrorFallback({
+    className,
+    recoveryAction,
+}: {
+    className?: string
+    recoveryAction: 'reload' | 'show-error'
+}): JSX.Element {
+    useEffect(() => {
+        if (recoveryAction === 'reload') {
+            console.error('App assets regenerated in a lazily loaded component. Reloading this page.')
+            reloadAfterChunkLoadError()
+        }
+    }, [recoveryAction])
+
+    if (recoveryAction === 'show-error') {
+        return (
+            <div className={clsx('ErrorBoundary', className)}>
+                <ErrorNetwork />
+            </div>
+        )
+    }
+
+    return (
+        <div className={clsx('ErrorBoundary', className)}>
+            <h2>Refreshing…</h2>
+            <p>PostHog just updated. Reloading the page now.</p>
+        </div>
+    )
+}
+
 export function ErrorBoundary({ children, exceptionProps = {}, className }: ErrorBoundaryProps): JSX.Element {
     const { currentTeamId } = useValues(teamLogic)
     const { openSupportForm } = useActions(supportLogic)
@@ -53,6 +87,7 @@ export function ErrorBoundary({ children, exceptionProps = {}, className }: Erro
                 const exceptionEvent = props.exceptionEvent as SupportTicketExceptionEvent
 
                 const isBrowserExtensionError = isDOMModificationError(normalizedError)
+                const chunkLoadRecoveryAction = getChunkLoadRecoveryAction(normalizedError)
 
                 const errorDetails = [
                     exceptionEvent?.uuid ? `Exception ID: ${exceptionEvent.uuid}` : null,
@@ -61,6 +96,10 @@ export function ErrorBoundary({ children, exceptionProps = {}, className }: Erro
                     .filter(Boolean)
                     .join('\n\n')
 
+                if (chunkLoadRecoveryAction !== 'ignore') {
+                    return <ChunkLoadErrorFallback className={className} recoveryAction={chunkLoadRecoveryAction} />
+                }
+
                 return (
                     <div className={clsx('ErrorBoundary', className)}>
                         <h2>An error has occurred</h2>
diff --git a/frontend/src/lib/utils/chunkLoadErrorRecovery.test.ts b/frontend/src/lib/utils/chunkLoadErrorRecovery.test.ts
@@ -0,0 +1,62 @@
+import {
+    CHUNK_LOAD_RELOAD_WINDOW_MS,
+    clearChunkLoadReloadAttempt,
+    getChunkLoadRecoveryAction,
+    isChunkLoadError,
+    markChunkLoadReloadAttempt,
+} from './chunkLoadErrorRecovery'
+
+describe('chunkLoadErrorRecovery', () => {
+    beforeEach(() => {
+        sessionStorage.clear()
+        clearChunkLoadReloadAttempt()
+    })
+
+    it('detects webpack chunk load errors', () => {
+        const error = new Error('Loading chunk 123 failed.')
+        error.name = 'ChunkLoadError'
+
+        expect(isChunkLoadError(error)).toBe(true)
+    })
+
+    it('detects esbuild dynamic import failures', () => {
+        expect(
+            isChunkLoadError(new Error('Failed to fetch dynamically imported module: /static/chunk-123.js'))
+        ).toBe(true)
+    })
+
+    it('ignores unrelated errors', () => {
+        expect(isChunkLoadError(new Error('TypeError: cannot read properties of undefined'))).toBe(false)
+        expect(getChunkLoadRecoveryAction(new Error('TypeError: cannot read properties of undefined'))).toBe('ignore')
+    })
+
+    it('reloads on the first chunk load failure', () => {
+        expect(getChunkLoadRecoveryAction(new Error('Failed to fetch dynamically imported module: /static/chunk.js'))).toBe(
+            'reload'
+        )
+    })
+
+    it('shows an error after a recent reload attempt', () => {
+        const now = 200_000
+        markChunkLoadReloadAttempt(now)
+
+        expect(
+            getChunkLoadRecoveryAction(
+                new Error('Failed to fetch dynamically imported module: /static/chunk.js'),
+                now + CHUNK_LOAD_RELOAD_WINDOW_MS - 1
+            )
+        ).toBe('show-error')
+    })
+
+    it('allows another reload after the cooldown window passes', () => {
+        const now = 200_000
+        markChunkLoadReloadAttempt(now)
+
+        expect(
+            getChunkLoadRecoveryAction(
+                new Error('Failed to fetch dynamically imported module: /static/chunk.js'),
+                now + CHUNK_LOAD_RELOAD_WINDOW_MS + 1
+            )
+        ).toBe('reload')
+    })
+})
diff --git a/frontend/src/lib/utils/chunkLoadErrorRecovery.ts b/frontend/src/lib/utils/chunkLoadErrorRecovery.ts
@@ -0,0 +1,56 @@
+const CHUNK_LOAD_RELOAD_MARKER_KEY = 'posthog:chunk-load-reload-at'
+export const CHUNK_LOAD_RELOAD_WINDOW_MS = 20_000
+
+export type ChunkLoadRecoveryAction = 'ignore' | 'reload' | 'show-error'
+
+function getSessionStorage(): Storage | null {
+    if (typeof window === 'undefined') {
+        return null
+    }
+
+    try {
+        return window.sessionStorage
+    } catch {
+        return null
+    }
+}
+
+function getChunkLoadReloadMarker(): number | null {
+    const marker = getSessionStorage()?.getItem(CHUNK_LOAD_RELOAD_MARKER_KEY)
+    if (!marker) {
+        return null
+    }
+
+    const parsed = Number(marker)
+    return Number.isFinite(parsed) ? parsed : null
+}
+
+export function isChunkLoadError(error: unknown): boolean {
+    if (!(error instanceof Error)) {
+        return false
+    }
+
+    return error.name === 'ChunkLoadError' || error.message.includes('Failed to fetch dynamically imported module')
+}
+
+export function getChunkLoadRecoveryAction(error: unknown, now = Date.now()): ChunkLoadRecoveryAction {
+    if (!isChunkLoadError(error)) {
+        return 'ignore'
+    }
+
+    const lastReloadAt = getChunkLoadReloadMarker()
+    return lastReloadAt && lastReloadAt > now - CHUNK_LOAD_RELOAD_WINDOW_MS ? 'show-error' : 'reload'
+}
+
+export function markChunkLoadReloadAttempt(now = Date.now()): void {
+    getSessionStorage()?.setItem(CHUNK_LOAD_RELOAD_MARKER_KEY, String(now))
+}
+
+export function reloadAfterChunkLoadError(now = Date.now()): void {
+    markChunkLoadReloadAttempt(now)
+    window.location.reload()
+}
+
+export function clearChunkLoadReloadAttempt(): void {
+    getSessionStorage()?.removeItem(CHUNK_LOAD_RELOAD_MARKER_KEY)
+}
diff --git a/frontend/src/scenes/sceneLogic.test.tsx b/frontend/src/scenes/sceneLogic.test.tsx
@@ -3,6 +3,7 @@ import { router } from 'kea-router'
 import { expectLogic, partial, truth } from 'kea-test-utils'
 
 import api from 'lib/api'
+import * as chunkLoadErrorRecovery from 'lib/utils/chunkLoadErrorRecovery'
 import { featureFlagLogic } from 'lib/logic/featureFlagLogic'
 import { Scene } from 'scenes/sceneTypes'
 import { teamLogic } from 'scenes/teamLogic'
@@ -50,6 +51,11 @@ describe('sceneLogic', () => {
         await expectLogic(logic).delay(1)
     })
 
+    afterEach(() => {
+        logic.unmount()
+        featureFlagLogic.unmount()
+    })
+
     it('has preloaded some scenes', async () => {
         const preloadedScenes = [Scene.Error404, Scene.ErrorNetwork, Scene.ErrorProjectUnavailable]
         await expectLogic(logic).toMatchValues({
@@ -60,6 +66,32 @@ describe('sceneLogic', () => {
         })
     })
 
+    it('routes to the network error scene after a repeated lazy import failure', async () => {
+        const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined)
+
+        try {
+            logic.unmount()
+            chunkLoadErrorRecovery.markChunkLoadReloadAttempt()
+
+            const brokenScenes = {
+                ...testScenes,
+                [Scene.DataManagement]: async () => {
+                    throw new Error('Failed to fetch dynamically imported module: /static/chunk.js')
+                },
+            }
+
+            logic = sceneLogic.build({ scenes: brokenScenes })
+            logic.cache.tabsLoaded = false
+            logic.mount()
+
+            await expectLogic(logic).delay(1)
+
+            expect(logic.values.sceneId).toBe(Scene.ErrorNetwork)
+        } finally {
+            consoleErrorSpy.mockRestore()
+        }
+    })
+
     it('changing URL runs openScene, loadScene and setScene', async () => {
         await expectLogic(logic).toDispatchActions(['openScene', 'loadScene', 'setScene']).toMatchValues({
             sceneId: Scene.DataManagement,
diff --git a/frontend/src/scenes/sceneLogic.tsx b/frontend/src/scenes/sceneLogic.tsx
@@ -11,6 +11,7 @@ import { FEATURE_FLAGS, TeamMembershipLevel } from 'lib/constants'
 import { trackFileSystemLogView } from 'lib/hooks/useFileSystemLogView'
 import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'
 import { Spinner } from 'lib/lemon-ui/Spinner'
+import { getChunkLoadRecoveryAction, isChunkLoadError, reloadAfterChunkLoadError } from 'lib/utils/chunkLoadErrorRecovery'
 import { getRelativeNextPath, identifierToHuman } from 'lib/utils'
 import { getAppContext, getCurrentTeamIdOrNone } from 'lib/utils/getAppContext'
 import { NEW_INTERNAL_TAB } from 'lib/utils/newInternalTab'
@@ -396,8 +397,6 @@ export const sceneLogic = kea<sceneLogicType>([
             tabId,
             params,
         }),
-        reloadBrowserDueToImportError: true,
-
         newTab: (
             href?: string | null,
             options?: { activate?: boolean; skipNavigate?: boolean; id?: string; source?: TabOpenSource }
@@ -640,13 +639,6 @@ export const sceneLogic = kea<sceneLogicType>([
                 setScene: () => null,
             },
         ],
-        lastReloadAt: [
-            null as number | null,
-            { persist: true },
-            {
-                reloadBrowserDueToImportError: () => new Date().valueOf(),
-            },
-        ],
         lastSetScenePayload: [
             {} as Record<string, any>,
             {
@@ -1294,20 +1286,13 @@ export const sceneLogic = kea<sceneLogicType>([
                     window.ESBUILD_LOAD_CHUNKS?.(sceneId)
                     importedScene = await props.scenes[sceneId]()
                 } catch (error: any) {
-                    if (
-                        error.name === 'ChunkLoadError' || // webpack
-                        error.message?.includes('Failed to fetch dynamically imported module') // esbuild
-                    ) {
-                        // Reloaded once in the last 20 seconds and now reloading again? Show network error
-                        if (
-                            values.lastReloadAt &&
-                            parseInt(String(values.lastReloadAt)) > new Date().valueOf() - 20000
-                        ) {
+                    if (isChunkLoadError(error)) {
+                        if (getChunkLoadRecoveryAction(error) === 'show-error') {
                             console.error('App assets regenerated. Showing error page.')
                             actions.setScene(Scene.ErrorNetwork, undefined, tabId, emptySceneParams, clickedLink)
                         } else {
                             console.error('App assets regenerated. Reloading this page.')
-                            actions.reloadBrowserDueToImportError()
+                            reloadAfterChunkLoadError()
                         }
                         return
                     }
@@ -1345,9 +1330,6 @@ export const sceneLogic = kea<sceneLogicType>([
             }
             actions.setScene(sceneId, sceneKey, tabId, params, clickedLink || wasNotLoaded, exportedScene)
         },
-        reloadBrowserDueToImportError: () => {
-            window.location.reload()
-        },
     })),
 
     // keep this above subscriptions
