fix: recognize Turbopack chunk-load errors for post-deploy auto-reload (#879)

## Problem

Prod error-monitor alert:

```
Error: Failed to load chunk /_next/static/chunks/<ID>.js from module <NUM>
    at https://gen.nomadkaraoke.com/_next/static/chunks/turbopack-*.js
```

The gen frontend is a static export (`output: 'export'`) served from
GitHub Pages with hashed chunk filenames. On deploy, old chunk hashes
vanish, so a user with an already-loaded tab hits a **post-deploy
mismatch** when the app lazy-loads a stale chunk. The frontend is
designed to auto-recover from this via `hardReload()` in
`client-error-setup.ts` — but the recovery wasn't firing.

## Root cause

`isChunkLoadError()` in `frontend/lib/version-check.ts` only recognized
webpack/native-ESM phrasings (`ChunkLoadError`, `Loading chunk <id>
failed`, `Failed to fetch dynamically imported module`, `Importing a
module script failed`).

**Next.js 16 defaults to Turbopack**, whose browser runtime throws a
plain `Error` (name `"Error"`, *not* `ChunkLoadError`) with a different
message: `Failed to load chunk <path> from module <n>` (also `… as a
runtime dependency of chunk <id>` / `… from an HMR update`). Confirmed
by inspecting the built runtime
`out/_next/static/chunks/turbopack-*.js`.

None of the regexes matched → the auto-hard-reload never triggered (user
saw a broken page) **and** the error was reported to the monitor → this
alert.

## Fix

- Add `/Failed to load chunk/i` to `isChunkLoadError()`'s regex list,
documenting all three bundler families.
- Add the first tests for `isChunkLoadError` (webpack, Turbopack ×3
variants, native ESM, negatives).
- Bump `0.191.1` → `0.191.2`.

Left the crash-reporter's `isBenignError` untouched: a chunk error that
survives the 60s reload circuit-breaker *should* still be reported
(persistent = a real problem like missing CDN files, not mere
staleness).

## Notes

- Users who already saw the error recover with a manual reload — this
fix makes future post-deploy mismatches self-heal automatically.
- The error store aggregates by pattern and does not persist
`user_email`, so the affected visitor can't be identified (and this hit
was on the logged-out `/zh/` homepage anyway).

## Testing

- `npx jest __tests__/version-check.test.ts
__tests__/CrashReport.test.tsx` → 20/20 pass
- `npx eslint` on changed files → clean

@coderabbitai ignore

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 4.8 authored and GitHub committed 2026-07-17 12:01:24 -04:00
1 parent 1578984f5b
commit eac3dac910
3 files changed
+52 -4

No files matched your search

+41 -1
View File
@@ -1,7 +1,47 @@
/**
* @jest-environment jsdom
*/
import { isStale, hardReload, __resetForTest, __setBuildShaForTest } from '@/lib/version-check'
import {
isStale,
hardReload,
isChunkLoadError,
__resetForTest,
__setBuildShaForTest,
} from '@/lib/version-check'
describe('version-check.isChunkLoadError', () => {
it('matches webpack ChunkLoadError by name', () => {
const e = new Error('boom')
e.name = 'ChunkLoadError'
expect(isChunkLoadError(e)).toBe(true)
})
it('matches webpack "Loading chunk <id> failed" message', () => {
expect(isChunkLoadError(new Error('Loading chunk 429 failed'))).toBe(true)
})
it.each([
// Turbopack (Next.js 16 default) — a plain Error, no ChunkLoadError name.
'Failed to load chunk /_next/static/chunks/e66613528f386db8.js from module 64893',
'Failed to load chunk /_next/static/chunks/abc.js as a runtime dependency of chunk 12',
'Failed to load chunk /_next/static/chunks/abc.js from an HMR update',
])('matches Turbopack chunk-load message: %s', (msg) => {
expect(isChunkLoadError(new Error(msg))).toBe(true)
})
it('matches native ESM dynamic-import failures', () => {
expect(
isChunkLoadError(new Error('Failed to fetch dynamically imported module: https://x/y.js')),
).toBe(true)
expect(isChunkLoadError(new Error('Importing a module script failed.'))).toBe(true)
})
it('ignores unrelated errors and falsy input', () => {
expect(isChunkLoadError(new Error('Cannot read properties of undefined'))).toBe(false)
expect(isChunkLoadError(null)).toBe(false)
expect(isChunkLoadError(undefined)).toBe(false)
})
})
describe('version-check.isStale', () => {
const fetchMock = jest.fn()
+10 -2
View File
@@ -112,8 +112,15 @@ export function hardReload(latestSha?: string): boolean {
/**
* Returns true if `err` looks like a chunk-load error from a post-deploy
* mismatch. Next.js surfaces these as `ChunkLoadError` or messages mentioning
* "Loading chunk" / "dynamically imported module".
* mismatch. Bundlers surface these differently:
*
* - webpack: `ChunkLoadError` / "Loading chunk <id> failed"
* - native ESM: "Failed to fetch dynamically imported module" /
* "Importing a module script failed"
* - Turbopack (Next.js 16 default): a plain `Error` whose message is
* "Failed to load chunk <path> from module <n>" (also "… as a runtime
* dependency of chunk <id>" / "… from an HMR update"). These carry NO
* `ChunkLoadError` name, so they must be matched by message.
*/
export function isChunkLoadError(err: unknown): boolean {
if (!err) return false
@@ -123,6 +130,7 @@ export function isChunkLoadError(err: unknown): boolean {
return (
/ChunkLoadError/i.test(msg) ||
/Loading chunk [\w-]+ failed/i.test(msg) ||
/Failed to load chunk/i.test(msg) ||
/Failed to fetch dynamically imported module/i.test(msg) ||
/Importing a module script failed/i.test(msg)
)
+1 -1
View File
@@ -1,6 +1,6 @@
[tool.poetry]
name = "karaoke-gen"
version = "0.191.1"
version = "0.191.2"
description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens."
authors = ["Andrew Beveridge <andrew@beveridge.uk>"]
license = "MIT"