Learning center

ChunkLoadError and Unexpected token '<' after a deploy

Chunk errors right after a deploy usually mean pages opened earlier are asking for script files the deploy removed. Whether the server answers 404 or the app's HTML decides the message and the fix.

Why old pages ask for missing files#

Bundlers split an app into chunks with hashed names, such as settings-4f2a91.js, and the page loads some of them later, when the user opens a route. A page loaded before the deploy still holds the old chunk names. If the deploy removed the old files, the user's next route change asks for a file that is gone. Vite's documentation describes this case: the hosting service may delete the previous deploy's assets, and a visitor from before the deploy hits an import error. Vite: load error handling

The two ways it fails#

The difference is what the server sends for a missing file.

Cause A: the server answers 404Cause B: the server answers 200 with the app's HTML
WhyThe old file was deleted and the server reports it missingA single-page-app fallback rewrites every unknown path to index.html
Dynamic import() in ChromiumFailed to fetch dynamically imported module: …The same, preceded by a strict MIME type error
Classic <script>The script fails to load with 404SyntaxError: Unexpected token '<'
Webpack's script-tag loaderChunkLoadError: Loading chunk 42 failed. (error: …)SyntaxError: Unexpected token '<', then ChunkLoadError: Loading chunk 42 failed. (missing: …)

In a local reproduction with Chromium, a page requested a missing module from a server that returned 404, then a second missing module from a server that returned an HTML page with 200:

GET /assets/missing-404.js     404
  Failed to load resource: the server responded with a status of 404 (Not Found)
  TypeError: Failed to fetch dynamically imported module:
    http://localhost:8101/assets/missing-404.js

GET /assets/spa-fallback.js    200  (Content-Type: text/html)
  Failed to load module script: Expected a JavaScript-or-Wasm module script but
  the server responded with a MIME type of "text/html". Strict MIME type checking
  is enforced for module scripts per HTML spec.
  TypeError: Failed to fetch dynamically imported module:
    http://localhost:8101/assets/spa-fallback.js

A classic script tag pointed at the HTML fallback produced SyntaxError: Unexpected token '<': the browser tried to run <!doctype html> as JavaScript. Strict MIME checking for module scripts · webpack's chunk error text

If the response carries X-Content-Type-Options: nosniff, Chrome refuses to run an HTML response as a script instead of parsing it. In a local check it printed Refused to execute script from '…/a.js' because its MIME type ('text/html') is not executable, and strict MIME type checking is enabled. and fired the script's error event: there is no SyntaxError, and webpack reports (error: …) as for a 404. Fetch standard: nosniff

In webpack's message, error means the script request itself failed, and missing means the script loaded but did not register the chunk, which is what happens when the file was HTML.

The deciding observation#

Select the failed script request in the Network panel and read two things: the status and the Content-Type of the response. A 404 is Cause A. A 200 with text/html, or a Response tab that starts with <!doctype html>, is Cause B.

Then confirm it is a deploy race and not a broken build: load the site fresh in a new tab and open the same route. If it works, the new deploy's chunks are fine and only pages from before the deploy fail. Record the time the failing page was loaded and the deploy time. The error tracker's first and last occurrence often match the deploy window.

Worked example: settings page fails only for open tabs#

This example is fictional. After a 15:00 deploy, the error tracker shows 40 Unexpected token '<' errors from settings-4f2a91.js between 15:00 and 16:30, then none.

The failing request returned 200 with Content-Type: text/html and the app's shell HTML. The new deploy's settings chunk was settings-b07c3e.js. A fresh tab loaded the settings page normally. Every error came from a session that started before 15:00.

The report said: pages loaded before the 15:00 deploy request settings-4f2a91.js, which the deploy removed. The server's fallback returns index.html with 200 for the missing path, so the browser runs HTML as script. Fresh loads work. The receiver had two separate changes to make: stop the fallback from answering for /assets/ paths, so a missing chunk is a clear 404, and keep the previous deploy's assets available for a while or reload the page when a chunk fails.

Choosing the fix#

Keeping old assets for a period after each deploy prevents the error for most open tabs. Reloading on a chunk error recovers the user, and Vite emits a vite:preloadError event that an app can listen for to do that. Vite: vite:preloadError Returning 404 for missing assets does not prevent the failure, but it makes the error say what happened. These are complementary; the report should say which ones the evidence supports.

What to put in the report#

  • The failing chunk's URL, status and Content-Type.
  • The chunk name the current deploy uses for the same route.
  • When the failing page was loaded and when the deploy finished.
  • Whether a fresh load works.

Questions#

Why do only some users see it?

Only users with a page open from before the deploy, who then load a chunk they had not loaded yet, request a removed file. Users who reload or arrive after the deploy get the new names.

Can a CDN keep the error going after the deploy?

Yes, long after the deploy, if a CDN location still serves the old HTML document that names chunks the origin no longer has. The old version guide shows how to find which cache served the document.

Is Unexpected token '<' always this problem?

No. It means JavaScript was given HTML. A fetch that calls response.json() on an HTML error page fails in a similar way. Look at which request returned HTML: a script request points here, an API request points at the API's error handling.

Return to the method for browser bug reports for the other symptoms in this collection.

One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. Eligibility and fair-use terms.

Start free with GitHub

Related reading