Vite "Error while updating dependencies", "The file does not exist at .vite/deps" and "504 (Outdated Optimize Dep)": Causes and Fixes
Vite "error while updating dependencies" and 504 Outdated Optimize Dep explained: what dependency pre-bundling is, why its cache goes stale, and fixes in order.
These errors all come from Vite's dependency pre-bundling: in development, Vite bundles your node_modules imports into a cache at node_modules/.vite/deps, and the errors appear when that cache and what the browser or dev server expects get out of step. Usually that happens after installing a package, switching branches or editing a linked package while the dev server is running. Restarting with vite --force, or deleting node_modules/.vite, fixes most cases. When it doesn't, the cause is a specific package, and optimizeDeps in your Vite config is where you fix it.
Checked against Vite's dependency pre-bundling guide, the optimizeDeps options, the troubleshooting page and the Vite source on GitHub in November 2026 (Vite 8.3).
What the errors look like
In the terminal running the dev server:
[vite] error while updating dependencies:
Error: ...
Newer Vite versions add an environment label, as in [vite] (client) error while updating dependencies:. The line after it is the actual cause, so read past the first line.
Also in the terminal, or as an error overlay in the browser:
The file does not exist at "/path/to/project/node_modules/.vite/deps/some-package.js?v=3f2a1b9c" which is in the optimize deps directory. The dependency might be incompatible with the dep optimizer. Try adding it to `optimizeDeps.exclude`.
And in the browser's console or Network tab:
GET http://localhost:5173/node_modules/.vite/deps/react.js?v=3f2a1b9c net::ERR_ABORTED 504 (Outdated Optimize Dep)
What dependency pre-bundling does
Vite serves your own source files to the browser as native ES modules, one file per import. Doing that for node_modules would break and be slow. The Vite docs give two reasons for pre-bundling:
- CommonJS and UMD packages have to be converted to ES modules before the browser can import them.
- Performance. Some packages are hundreds of small modules. The docs' example is
lodash-es, with over 600 internal modules, which pre-bundling turns into a single request.
On the first start, Vite scans your source for bare imports (import React from 'react'), bundles those packages and writes the result to node_modules/.vite/deps. Each file is served with a ?v= hash and cached by the browser with max-age=31536000,immutable.
Vite rebuilds this cache when any of these change:
- your package manager's lockfile (so installing or upgrading a package triggers it)
- the modification time of a
patchesfolder - relevant fields in
vite.config.* NODE_ENV
It also rebuilds while running if it finds an import it hadn't seen before.
What each error means
504 (Outdated Optimize Dep) is often not a bug. When Vite discovers a new dependency mid-session, it re-bundles, the ?v= hashes change, and it triggers a full page reload. Requests the browser had already started for the old files get a 504 with this status text. The Vite source says as much: "a normal part of the missing deps discovery flow". If the page reloads and works, ignore it. If you see it on every load, the browser or the dev server is stuck on stale files.
"The file does not exist at ... .vite/deps" means the browser requested a pre-bundled file that isn't in the cache directory. Either the cache was rebuilt or deleted underneath a running page, or the optimizer genuinely can't produce a file for that package. The message suggests optimizeDeps.exclude, but try clearing the cache first. Excluding a package that needed bundling can create new errors.
"error while updating dependencies" means a re-bundle failed. The causes are the same, plus a package that fails to bundle (a syntax error the bundler can't handle, a missing file because npm install was still running, a package that depends on something not installed).
Fixes, least disruptive first
1. Reload the page, then restart the dev server
If you just installed a package or Vite printed "new dependencies optimized", reload once. If the errors persist, stop the dev server (Ctrl+C) and start it again. Don't run npm install or switch branches while it's running; stop it first.
2. Restart with --force
--force tells Vite to ignore the cache and re-bundle everything:
npx vite --force
# or through your package.json script, if "dev" runs vite:
npm run dev -- --force
The equivalent config option is optimizeDeps.force: true, but leaving that on permanently makes every start slower.
3. Delete the cache folder
node_modules/.vite contains only generated cache. Deleting it is safe; Vite rebuilds it on the next start. Stop the dev server first.
rm -rf node_modules/.vite
On Windows PowerShell:
Remove-Item -Recurse -Force node_modules\.vite
If your config sets cacheDir, delete that directory instead. Framework CLIs built on Vite may also put the cache somewhere else, so check their docs.
4. Clear the browser's cached copies
Because pre-bundled files are cached as immutable, a browser tab can keep requesting files that no longer exist. For dependency issues, Vite's docs recommend this combination: open DevTools, tick Disable cache in the Network tab (it only applies while DevTools is open), restart Vite with --force, and reload. A hard refresh also works (how to hard refresh).
If you use a self-signed HTTPS certificate for the dev server, Vite's troubleshooting page notes that Chrome ignores caching directives in that case, which breaks the caching Vite relies on. Use a trusted local certificate.
5. Linked packages and monorepos
Vite's docs are explicit that it won't invalidate the cache when you npm link or unlink a package, and that linked packages need a forced re-optimization:
In case you link or unlink a dependency, you'll need to force re-optimization on the next server start by using
vite --force.
In a monorepo, packages linked from the same repository are treated as source code, not pre-bundled. If one of them isn't ES modules (it ships CommonJS), add it to optimizeDeps.include:
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
optimizeDeps: {
include: ['@acme/shared-utils'],
},
})
After changing a linked package's code in a way that affects its bundled output, restart with --force. Also note that Vite's file watcher ignores node_modules, so edits to a package installed there won't trigger updates.
6. Tune optimizeDeps for a problem package
When the same package keeps failing after a clean cache, tell the optimizer how to treat it:
optimizeDeps.include: force a package to be pre-bundled. Use it for dependencies that are imported dynamically or only discovered late (for example, behind a plugin), which otherwise trigger the mid-session re-bundle and reload. It also accepts deep imports like'my-lib/components/Button'.optimizeDeps.exclude: skip pre-bundling for a package that is already valid ESM and breaks when bundled. Don't exclude CommonJS packages. If an excluded ESM package has a CommonJS dependency, include that nested one with the'esm-dep > cjs-dep'syntax.
export default defineConfig({
optimizeDeps: {
include: ['lodash-es', 'some-esm-lib > some-cjs-dependency'],
exclude: ['some-esm-lib'],
},
})
When late discovery forces a reload during cold start, Vite prints a line starting tip: consider adding ... to optimizeDeps.include. Taking that suggestion usually removes recurring 504s.
In Vite 8, low-level bundler settings for the optimizer go in optimizeDeps.rolldownOptions. The older optimizeDeps.esbuildOptions is deprecated.
7. Reinstall dependencies (last resort)
If a package's files are genuinely missing or corrupted, for example after an interrupted install, reinstall:
rm -rf node_modules
npm install
Keep your lockfile. Deleting it as well changes the versions you get, which is a separate decision. (node_modules explained covers what's in that folder.)
If it only happens in one place
- Only in CI or a fresh clone: check that the lockfile is committed and that
npm ci(notnpm install) is used, so the installed tree matches what you tested. - Only after
git checkout: a different lockfile on another branch changes the cache hash. Restart the dev server after switching. - Only for one package after an upgrade: check that package's changelog for a switch between CommonJS and ESM, then use
includeorexcludeas above. - The error names a module that isn't installed at all: that's a resolution problem, not a cache problem. See Module not found: Can't resolve.
These errors are development-only. vite build uses a separate production bundling pipeline, so a dev-server cache problem won't follow you into production builds.
Quick checklist
- Reload once; ignore a single 504 that's followed by a working page.
- Stop the server, then
npm run dev -- --force. - Still failing: delete
node_modules/.viteand start again. - Disable the browser cache in DevTools and reload.
- Linked or monorepo package: add it to
optimizeDeps.includeand restart with--force. - One package keeps failing:
includeorexcludeit. - Last resort: reinstall
node_modules, keeping the lockfile.
For background on why Vite works this way, see What is Vite? and Webpack vs Vite.
On EasySpawn, the dev server runs on a persistent server with Claude Code beside it, so when a dependency cache goes stale the agent can restart the server with --force and check the result at the branch's live URL. See how it works or join the waitlist.
Related: What Is Vite? The Build Tool Behind Lovable and Bolt Apps, Explained · Module not found: Can't resolve — How to Fix It (Next.js, Vite, webpack) · Webpack vs Vite: What a Bundler Does and Which One to Use · How to Hard Refresh and Clear the Cache (Chrome, Safari, Firefox, Edge)
Keep reading
Next.js "An error occurred in the Server Components render": Finding the Real Error Behind the Digest
Next.js error digest explained: why production hides Server Component errors, how to match the digest to your server logs, and the usual root causes.
React Error Boundaries: Stop One Broken Component Crashing the Page
Without an error boundary, one component throwing during render blanks your entire React app. How error boundaries work, using react-error-boundary with fallbacks and reset, Next.js error.tsx and global-error.tsx, what boundaries don't catch, and reporting errors to monitoring.