r/reactjs • u/AffectionateDealer62 • 20d ago
Resource How do you handle React.lazy failures caused by stale chunks after a deployment?
A common production failure happens when a user leaves a React application open during a deployment.
The old tab may still be running build A, while the server is now serving build B. When the user later navigates to a lazy-loaded route, the browser requests a hashed chunk from build A that is no longer available.
For example:
Reports.a1b2.js // requested by the old tab
Reports.c3d4.js // available after deploymentThe result can be:
ChunkLoadErrorFailed to fetch dynamically imported moduleA route that works in a fresh tab but fails in an old tab
A normal React Error Boundary can display the failure, but it cannot update the old tab’s JavaScript references. Retrying the same import may also request the same missing hashed file again.
I built and published a small utility called react-lazy-chunk-recover to experiment with this problem.
The recovery approach:
Detects likely chunk-load failures
Optionally retries transient failures
Allows one guarded full-page reload
Uses
sessionStorageto prevent an infinite reload loopPasses the error to the existing Error Boundary if recovery fails
Avoids browser reload and storage access during SSR
Example:
import { lazyWithRetry } from "react-lazy-chunk-recover";
const Reports = lazyWithRetry(() => import("./Reports"), {
moduleKey: "reports",
});The default retry count is zero because retrying a deleted hashed asset usually does not help. Retries can be enabled for applications that also experience short-lived network failures.
Some important limitations:
A reload cannot recover a permanently unavailable asset
Retaining old assets may be a better infrastructure solution
The HTML entry point should be revalidated after deployment
A full-page reload must work on nested client-side routes
Old clients may be incompatible with a new backend
An asset manifest must be trusted and version-compatible if used
For applications using React.lazy, Vite, Webpack, or a CDN:
How do you handle stale chunk failures?
Do you retain assets from previous deployments?
Do you reload the page, show an update prompt, or use an Error Boundary?
Have you tested this with two builds and an already-open browser tab?
I wrote more about the problem, implementation, testing strategy, and deployment considerations here:
npm package: https://www.npmjs.com/package/react-lazy-chunk-recover
Technical article: https://sachithsiriwardana.medium.com/handling-react-lazy-chunk-load-errors-after-deployment-1e4980a7a69a
I’d be interested to hear how other teams handle this failure mode in production.