Vite 'Failed to Fetch Dynamically Imported Module' After Deploy
Users see a blank page or a broken route right after you deploy a Vite app? Learn why old chunks return 404, and fix it with a safe reload handler and a better deploy setup.
"Failed to fetch dynamically imported module" in a Vite app almost always means a user's open tab asked for a hashed JavaScript file that your last deploy deleted. The fix has three parts: keep old assets online for a while, listen for the vite:preloadError event and reload once, and make sure missing files return a 404 instead of your HTML page.
The error looks like this in Chrome:
TypeError: Failed to fetch dynamically imported module:
https://app.example.com/assets/Settings-3f9a1c2b.js
Safari and Firefox word it differently ("Importing a module script failed" is common), but the cause is the same. This guide shows how to confirm it, fix it, and notice it before your users do.
Step 1: Understand why it happens
Vite builds every lazy route (React.lazy, import()) into its own file. The file name contains a hash of its content, such as Settings-3f9a1c2b.js. When you change that component, the hash changes.
Now picture a user who opened your app an hour ago. Their browser holds the old index bundle. It still points to Settings-3f9a1c2b.js. You deploy. Your host replaces the whole dist folder, so that file is gone. The user clicks "Settings", the browser asks for the old file, gets a 404, and the import fails.
This is why the error shows up right after a deploy and then fades. It also explains why it hits long-lived tabs and logged-in dashboards the most. Reports on Stack Overflow and in the RedwoodJS issue tracker describe exactly this pattern.
If you use Next.js instead, the same root cause appears as a different error. See ChunkLoadError after deploy in Next.js.
Step 2: Confirm it is a stale chunk
Not every instance of this error is a deploy problem. Check these in order:
- Open DevTools, Network tab, and reproduce the error.
- Find the failing
.jsrequest. Look at the status code and the response. - A 404 on a hashed file after a recent deploy means a stale chunk. This guide applies.
- A 200 with a
text/htmlresponse means your server returnedindex.htmlfor a file that does not exist. That is a server rewrite bug (Step 4). A Laracasts thread shows this variant with a MIME type error. - A failed request with no status (blocked, offline, CORS) is a network problem, not a deploy problem.
Also check your deploy log. A DEV Community post describes a case where a rollback turned off automatic domain assignment on Vercel, so later pushes never reached the live site. The chunks looked "missing" because production was serving an old build.
Step 3: Reload once when a chunk fails
Vite fires a vite:preloadError event on window when a dynamic import fails to load. If you do not cancel it, Vite rethrows the original error. Add a handler early in your entry file (main.tsx):
// main.tsx
const RELOAD_KEY = 'chunk-reload-at'
window.addEventListener('vite:preloadError', (event) => {
event.preventDefault() // stop Vite from rethrowing
try {
const last = Number(sessionStorage.getItem(RELOAD_KEY) ?? 0)
// Reload at most once every 30 seconds to avoid a loop
if (Date.now() - last < 30_000) return
sessionStorage.setItem(RELOAD_KEY, String(Date.now()))
} catch {
return // storage blocked: do not risk a reload loop
}
window.location.reload()
})
The 30-second guard matters. Community write-ups warn that a blind reload can loop forever if the file is truly missing or the network is down. The same event also fires for offline and CORS failures, where a reload only throws away the user's unsaved state. Check this Vite issue for the typing gap: the event is not declared in the global types, so TypeScript may need a small declaration.
A reload fetches the new index.html, which points to the new chunk names. The user lands on the new version.
Step 4: Return a real 404 for missing assets
Single page apps usually rewrite every unknown URL to index.html. That is right for /settings and wrong for /assets/Settings-3f9a1c2b.js. If the rewrite catches asset paths, the browser receives HTML where it expected JavaScript. You get a confusing MIME error and the browser may cache the bad answer.
For nginx, serve real files first and only fall back for page routes:
location /assets/ {
try_files $uri =404;
}
location / {
try_files $uri /index.html;
}
On Netlify, Vercel and Cloudflare Pages, check that your rewrite rule excludes /assets/*. Then your handler from Step 3 receives a clean failure and can recover.
Step 5: Keep old assets for a few days
The strongest fix is to stop deleting the old files. Upload new assets next to the old ones and clean up later.
- Object storage or CDN (S3, R2, GCS): sync the new
distwithout the delete flag, and remove files older than 7 days with a lifecycle rule. - Single server: deploy into a new release folder, keep the last 2 or 3 builds'
assetsfolders, and serve them from one path. - Static hosts such as Vercel and Netlify: these keep each deploy at its own URL, but production traffic only points at the latest one. Rely on Steps 3 and 4 there.
Cache headers help too. Hashed files can be cached for a year because the name changes with the content. The index.html file must not be cached for long:
/assets/* Cache-Control: public, max-age=31536000, immutable
/index.html Cache-Control: no-cache
With no-cache, a returning user gets the new HTML soon after your deploy, which shrinks the window where a stale tab exists.
Step 6: Watch for it after every deploy
You will not see this error in your own browser because you always load the newest build. Users report it as "the page went white" and rarely send details. The useful signals are:
- A spike in
Failed to fetch dynamically imported moduleevents right after a deploy time. - Which route and which browsers it hit.
- Whether it went down on its own once users reloaded.
Add a quick smoke test to your deploy pipeline: request the production index.html, read the main script URL from it, and check that every URL returns 200 with a JavaScript content type.
How Relia Helps
Relia watches the browser side of a live product. When this error spikes after a deploy, it joins the deploy time, the failing chunk request and the users who hit it into one incident explained in plain words, and shows who was affected. After you ship a fix, it checks whether the errors actually stopped. Install it in a Vite app with npx relia-sdk@latest init. You can see how an incident looks in the live demo.
FAQ
Why does this only happen in Chrome for some people?
Chrome caches a failed dynamic import for the life of the page, so a retry on the same page keeps failing until a full reload. Other browsers may re-fetch. This is described in the Stack Overflow answers for this error, which is why Step 3 reloads the whole page instead of retrying the import.
Can I stop it by disabling code splitting?
You can ship one big bundle, but you pay in load time for every user. Fixing deploy behavior is cheaper.
Does React.lazy need an error boundary?
Yes, as a last line of defense. Wrap lazy routes in an error boundary that shows a "New version available, reload" button. See React error handling in production for related patterns.
Is it always a deploy problem?
No. A 200 response with HTML, an offline user, a blocked CDN or a dependency optimizer bug can cause the same message. Step 2 tells them apart.