The Symptom: A White Screen of Death
You’re using a Next.js application, likely deployed on a modern JavaScript runtime like Cloudflare Workers. You’ve been browsing the site, clicking through links, navigating between pages. Then, without warning, your next click results not in the expected content, but a stark white screen. The only message displayed is a generic error: Application error: a client-side exception has occurred (see the browser console for more information).
This error is particularly frustrating because a simple page reload immediately resolves the issue. Everything works as expected, and you can continue your session as if nothing happened. This intermittent nature suggests a race condition or a timing-sensitive problem rather than a fundamental bug in your application logic.
This specific error, encountered by developers running Next.js applications, especially those utilizing the App Router and deploying to edge environments like Cloudflare Workers, points to a deeper issue: stale JavaScript chunks. When a new version of your application is deployed, the server-side rendering (SSR) or server components might serve updated HTML, but the client-side JavaScript bundles—the chunks that enable client-side navigation and interactivity—might not have been updated or fetched correctly. This mismatch leads to the client attempting to execute outdated or non-existent code, triggering the dreaded client-side exception.
Understanding the Root Cause: Stale Chunks and Mismatched Builds
The core of the problem lies in how modern JavaScript frameworks like Next.js handle code splitting and dynamic imports. To optimize performance, applications are often broken down into smaller JavaScript chunks. These chunks are loaded on demand as the user navigates through the application. When you deploy a new version of your Next.js app, you are essentially replacing these JavaScript bundles on your server or CDN.
The issue arises when the server serves an updated HTML page (perhaps with new server-rendered content or updated metadata) that references JavaScript chunks from the *new* build, but the browser's cache or the edge worker still holds references to or attempts to load JavaScript chunks from an *older* build. This can happen for several reasons:
- Cache Invalidation Issues: CDNs or edge caches might not invalidate older JavaScript files correctly when a new deployment occurs.
- Build Propagation Delays: In distributed systems, there can be a small window where different nodes or edge locations have different versions of the application's assets.
- Client-Side Cache: While less common for critical application chunks, browser caching mechanisms could theoretically contribute if not managed properly.
The Next.js App Router, with its focus on server components and dynamic rendering, can sometimes exacerbate this. The HTML might be fully rendered on the server with references to new client bundles. If the client then requests one of these new bundles but finds an older version served by the edge (due to caching or propagation delays), it leads to a 404 error for that specific chunk. The application, unable to load essential client-side logic, fails spectacularly with the generic exception.
The Stale Chunk 404: A Specific Failure Mode
When the browser receives the updated HTML, it parses the references to JavaScript files. If a script tag points to _next/static/chunks/chunk-abc123.js, and this specific file doesn't exist at the requested URL on the server or CDN (because it was part of a previous build that has since been superseded), the browser receives a 404 Not Found error for that script. The Next.js client-side hydration or routing logic then encounters this missing script, cannot execute the necessary JavaScript, and throws the Application error: a client-side exception has occurred.
The key here is that the error isn't a generic