504 (Outdated Optimize Dep) on localhost:5173

What does the 504 actually mean?

Pre-bundled dependencies are served under a URL that carries a version hash, for example /node_modules/.vite/deps/dayjs.js?v=c3d2a1ba. When Vite re-bundles, the hash changes. A request that still carries the old hash is not answered with the old file. The server sets status 504 with the status text "Outdated Optimize Dep" and sends an empty body. Internally the error reads: there is a new version of the pre-bundle, and a page reload is going to ask for it.

What triggers the re-bundle?

Vite scans your entry points at startup and pre-bundles the bare imports it finds. An import it did not see — in a file created after the server started, or reachable only through a path the scanner did not follow — is found when the browser first requests that module. Vite then runs the bundling again. The docs describe it this way: if a new dependency import is encountered that is not already in the cache, Vite re-runs the bundling and reloads the page if needed. The terminal shows it:

# a file importing "ms" was requested after startup
10:04:56 [vite] (client) dependency optimized: ms
10:04:56 [vite] (client) optimized dependencies changed. reloading

Why do I see the 504 and not just a reload?

A request that still carries the old hash gets the 504. The server invalidates its module graph and sends a full-reload event to the connected pages, but a module the page asked for just before the re-bundle finished, or a tab that missed the event, still holds the old URL. In a healthy session the reload that follows replaces the page, the new page asks for the new URLs, and the 504 is a single line in the Network tab that you can ignore.

When does it stay broken?

When the reload never happens. The full-reload event travels over the HMR connection, so a page whose WebSocket is not connected — behind a proxy or tunnel that does not forward it, or in a tab that was open while the server restarted — keeps requesting the old hash and keeps getting 504s. A manual reload is the fix for that tab. If it recurs on every start, look at the socket first, not at the pre-bundle.

• One 504, page reloads by itself — normal re-bundle, nothing to fix.
• 504 on every dependency, page never reloads — the HMR WebSocket is not connected.
• 504 again after a manual reload — a dependency is still being discovered late, see below.

How do I stop it from recurring?

Tell Vite about the dependency before the browser asks for it. A package the scanner cannot see goes into optimizeDeps.include, which pre-bundles it at startup. In a local test with 8.3.4, importing an included package from a file created later caused no new optimization, and the existing dep URLs stayed at 200. Vite also hints at this itself: on a late discovery during cold start it prints a tip to add the package to optimizeDeps.include.

export default {
  optimizeDeps: {
    include: ['ms']   // pre-bundled at startup, not on first request
  }
}

Is this the same as the other 504s?

No. The dev server has three 504 responses around dependency optimization, and they point to different causes. "Outdated Optimize Dep" is the stale hash described here. "Optimize Deps Processing Error" means the optimizer itself failed on a package, and the error is printed in the terminal. "Outdated Request" means the request arrived while the server was closing. A fourth, related response is a 404 for a file that does not exist inside the optimized directory; its message suggests optimizeDeps.exclude for that package.

Is there an option that turns the error off?

There is one in the type definitions: optimizeDeps.ignoreOutdatedRequests, default false, marked experimental. Its own comment warns that enabling it may cause a single module to have multiple references. It does not appear on the vite.dev options page, so treat it as unsupported and fix the cause instead.

Does clearing the cache help?

Not for this error. The stale hash is a runtime state of the running server, not a stale file on disk. Restarting the server and reloading the page resets it. Clearing node_modules/.vite is only needed when the browser keeps serving old dependency code after the files changed — see the page on the cache.

• What happens between npm run dev and the page on localhost:5173Starting the Vite dev server takes five steps: npm resolves the vite binary, Vite reads the config, dependencies are pre-bundled, the server listens on 5173, and the browser opens an HMR WebSocket on the first request.
• Dependency pre-bundling on the Vite dev serverVite converts your dependencies to ESM once before serving them on 5173 and caches the result in node_modules/.vite — optimizeDeps controls what goes into that step and what stays out of it.
• Clearing the Vite dependency cacheVite caches pre-bundled dependencies in node_modules/.vite — delete that directory or start with --force to rebuild it.
• localhost:5173 — the port itselfWhat the address means, common dev ports, and the autocomplete fix.