ChunkLoadError: Loading chunk failed after a Next.js deploy
ChunkLoadError: Loading chunkShort answer
A browser asked for a JavaScript file that the server no longer has or that another instance never built. The usual cause is version skew: an open tab from the old deploy requests chunks from the new one. Set a deploymentId so Next.js reloads the page on a mismatch, and run one build on every instance.
Fix it fast
1Find out which cause you have
Open the browser network tab on the failing page and look for the failed request under /_next/static. A 404 there means the file is gone; a different host means an asset prefix problem.
curl -s https://example.com/ | grep -o '/_next/static/[^"]*\.js[^"]*' | head -32Match what you see, then jump to its fix
What does the error look like?
ChunkLoadError: Loading chunkMissing assets: the client requests JavaScript or CSS files that no longer exist on the server
Cause 1 of 2
Version skew after a deploy
1Check
The old page references chunk files from the previous build. Once the new build replaces them, those requests fail.
curl -s https://example.com/ | grep -o 'dpl=[^"&]*' | head -12Fix
Set a deployment ID. Next.js then adds ?dpl=<id> to asset URLs and an x-deployment-id header to navigation requests, and does a full page reload instead of a client navigation when the IDs differ.
// next.config.js
module.exports = {
deploymentId: process.env.DEPLOYMENT_VERSION,
}3Verify
Deploy twice with different values and navigate in a tab that was open before the second deploy; it should reload.
DEPLOYMENT_VERSION=$(git rev-parse --short HEAD) npm run buildConfirmed by nextjs.org
Cause 2 of 2
Instances behind a load balancer run different builds
1Check
Next.js generates an ID during next build to identify the version being served, and the same build should be used to boot every container. If each container builds on its own, a request can reach an instance with a different build.
grep -n "generateBuildId\|deploymentId" next.config.*2Fix
Build once and start every container from that build. If you must build per environment, generate the same build ID everywhere.
// next.config.js
module.exports = {
generateBuildId: async () => {
return process.env.GIT_HASH
},
}3Verify
Take one script URL from the page source and request it several times through the load balancer; every answer should be 200.
for i in 1 2 3 4 5; do curl -s -o /dev/null -w '%{http_code}\n' "$CHUNK_URL"; doneConfirmed by nextjs.org
How do I stop it coming back?
- Keep old static assets available for a while after a release, or use immutable assets.
- Set deploymentId in every production build.
- Build one artifact and promote it, instead of rebuilding per environment.
- Watch client error reports for ChunkLoadError right after each release.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Web 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
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix