504 (Outdated Optimize Dep)

# stop the dev server, then:
rm -rf node_modules/.vite
npm run dev -- --force        # rebuild the dependency pre-bundle from scratch

What you're seeing

# in the browser console / network tab
GET http://localhost:5173/node_modules/.vite/deps/lodash-es.js?v=8f2a1c3d
    504 (Outdated Optimize Dep)

# in the Vite terminal
[vite] ✨ new dependencies optimized: chart.js
[vite] ✨ optimized dependencies changed. reloading

The ?v= hash in the URL is the tell: the browser asked for one pre-bundle version and Vite has already moved to a new one. That "reloading" line in the terminal is Vite re-optimizing underneath you.

Fix 1 — Reload the page

When: a one-off 504 the first time a new dependency is hit.

# nothing to install — just refresh
# Vite finishes optimizing and serves the new pre-bundle
# (Cmd/Ctrl + R)

The first time Vite encounters a dependency it hasn't pre-bundled, it optimizes it and reloads. A single 504 during that hand-off is expected; one refresh clears it.

Fix 2 — Wipe the optimize cache and force a rebuild

When: the 504 won't go away, or the cache looks corrupted after a crash.

# stop the dev server first
rm -rf node_modules/.vite       # delete the pre-bundle cache
npm run dev -- --force          # or: vite --force

# nuke a stale browser copy too if needed: hard reload / disable cache

node_modules/.vite holds the esbuild pre-bundles. Deleting it plus --force makes Vite re-derive everything cleanly, which fixes a stale or half-written cache.

Fix 3 — Pre-declare deps so Vite stops re-optimizing

When: recurring 504s because Vite keeps discovering deps at runtime.

// vite.config.js
export default {
  optimizeDeps: {
    include: ['lodash-es', 'chart.js', 'date-fns'], // bundle up front
    // exclude: ['some-pkg-using-workers'],          // skip when needed
  },
};

If deps are only discovered when a route lazy-loads them, Vite re-optimizes mid-session and invalidates chunks — the classic repeating 504. Listing heavy or dynamically imported packages in optimizeDeps.include makes Vite pre-bundle them at startup, so the cache stays stable.

Fix 4 — Restart after any dependency change

When: it began right after npm install, an update, or npm link.

# after changing dependencies, restart the dev server
# (Ctrl-C, then)
npm run dev

Installing or updating a package changes the lockfile, so Vite re-runs optimization and old pre-bundle URLs go stale. A restart re-derives the cache; you rarely need --force for this case.

Why this happens

For fast dev startup, Vite pre-bundles your node_modules dependencies with esbuild into node_modules/.vite/deps and serves them with a version query (?v=hash). If Vite later decides the pre-bundle is out of date — it discovered a new dependency to include, the lockfile changed, or the config changed — it re-optimizes and assigns a new hash. Any browser request still pointing at the old hash can no longer be served, so Vite responds 504 (Outdated Optimize Dep) to tell the client "this pre-bundle is stale, reload." It reuses the HTTP 504 code but has nothing to do with a gateway timeout. Because it's purely the dev-server dependency cache, the fixes are all about clearing or stabilizing that cache — and it never affects vite build.

Quick reference