webpack lazy-loaded chunk fails to load (ChunkLoadError)
ChunkLoadError: Loading chunk 123 failed.Short answer
ChunkLoadError means the browser asked for a split-out JavaScript file and did not get it. Open the Network tab and look at the URL of the failed request. A wrong path points to output.publicPath. A 404 on an old hashed name points to files removed by a newer deploy. A long wait points to chunkLoadTimeout.
Fix it fast
1Find out which cause you have
Open DevTools, Network tab, and find the chunk request that failed. Copy its URL and request it from the shell to see the status.
curl -I https://example.com/static/js/123.abc123.chunk.js2Match what you see, then jump to its fix
- 1
The failed URL has the wrong folder, for example /123.js when the files live under /app/output.publicPath points to the wrong placeFix - 2
The error shows up in tabs that were open before a deploy; the failed file has an old hash and returns 404A new deploy removed the old hashed chunksFix - 3
The error appears only after a long wait (about two minutes by default)A preloaded script failed and webpack waits for the timeoutFix
- 1
What does the error look like?
ChunkLoadError: Loading chunk 123 failed.Loading chunk 123 failed.
Cause 1 of 3
output.publicPath points to the wrong place
1Check
publicPath is the base URL every chunk is requested from. If the app is served from a sub-folder or a CDN and publicPath is still the default, chunks are requested from the wrong place.
grep -n "publicPath" webpack.config.*2Fix
Set publicPath to where the built files are really served. Use "auto" when the path is not known in advance, so webpack works it out at runtime.
export default {
output: {
publicPath: "auto",
},
};3Verify
Rebuild, deploy and load the page: the chunk request now returns 200.
npx webpack --mode productionConfirmed by webpack.js.org
Cause 2 of 3
A new deploy removed the old hashed chunks
1Check
Filenames with [contenthash] change when content changes, and output.clean empties the output folder before each build. A page loaded before the deploy still asks for the old names.
grep -n -E "contenthash|clean" webpack.config.*2Fix
Keep older chunks in the output folder for a while (output.clean can keep files that match a pattern; delete them on a schedule so they do not pile up), and catch the failure in the code that calls import() so you can reload the page.
// webpack.config.js
output: {
clean: { keep: /\.chunk\.js$/ },
},
// where you load the chunk
import("./Dashboard").catch((err) => {
if (err.name === "ChunkLoadError") window.location.reload();
throw err;
});3Verify
Deploy twice with a tab left open in between, then trigger the lazy import in the old tab.
ls distConfirmed by webpack.js.org
Cause 3 of 3
A preloaded script failed and webpack waits for the timeout
1Check
If a script tag for the chunk was added by hand and it fails before webpack attaches its own error handler, the import() promise settles only when output.chunkLoadTimeout runs out. The default is 120000 ms.
grep -n "chunkLoadTimeout" webpack.config.*2Fix
Add onerror="this.remove()" to that script tag so webpack creates its own tag and handles the failure at once. You can also lower chunkLoadTimeout.
<script src="https://example.com/dist/dynamicComponent.js" async
onerror="this.remove()"></script>3Verify
Block that script in DevTools and trigger the lazy import. The error now appears quickly.
grep -n "onerror" dist/index.htmlConfirmed by webpack.js.org
How do I stop it coming back?
- Deploy with the same publicPath that your server or CDN uses, and test a lazy route on the deployed site.
- Keep the last build's chunks online for some time after each deploy.
- Wrap lazy imports so a ChunkLoadError causes a reload instead of a blank screen.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
tsconfig rejects allowImportingTsExtensions
An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly
allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.
2 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fix