Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

ChunkLoadError: Loading chunk failed after a Next.js deploy

ErrorChunkLoadError: Loading chunk

Short 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.

  • Applies to Next.js 15, Next.js 16, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 -3
  2. 2Match what you see, then jump to its fix

    1. 1Errors start right after a release, for visitors whose tab was already openVersion skew after a deployFix
    2. 2The error is intermittent and the same chunk URL works on some requests and gives 404 on othersInstances behind a load balancer run different buildsFix

What does the error look like?

  • ChunkLoadError: Loading chunk
  • Missing 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 -1

2Fix

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 build

Confirmed by nextjs.org

Did this fix it?

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"; done

Confirmed by nextjs.org

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.