Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Vite answers a request with 504 Outdated Optimize Dep

Error504 (Outdated Optimize Dep)

Short answer

This 504 is how the Vite dev server says a request refers to an out-of-date pre-bundle. Vite found a new dependency, rebuilt its optimized files and reloaded the page, so older requests can no longer be served. It is normal once. If it repeats, pre-bundle the dependency up front or clear the cache.

  • Applies to Vite 8, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Watch the terminal when the error appears. A line about new dependencies being found and optimized means case one below.

    npx vite --force
  2. 2Match what you see, then jump to its fix

    1. 1The terminal reports a dependency being optimized, then the page reloadsA dependency was discovered after the server startedFix
    2. 2You use npm link or a workspace link and the error follows changes in that packageA linked package changed and the cache was not rebuiltFix
    3. 3It started after a lockfile, config or patch change, or after switching branchesThe cache in node_modules/.vite is staleFix

What does the error look like?

  • 504 (Outdated Optimize Dep)

Cause 1 of 3

A dependency was discovered after the server started

1Check

Vite crawls your source on first run. A package imported lazily or created by a plugin is found later, so Vite re-runs dependency bundling and reloads. Requests made before the reload get the 504.

ls node_modules/.vite/deps

2Fix

Name the dependency in optimizeDeps.include so it is bundled before the first request.

// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
  optimizeDeps: { include: ['some-lazy-package'] },
})

3Verify

Restart with a fresh cache and load the page that imports it; no reload should happen.

npx vite --force

Confirmed by vite.dev

Did this fix it?

Cause 2 of 3

A linked package changed and the cache was not rebuilt

1Check

Vite does not notice changes in linked packages by itself.

ls -l node_modules | grep -- '->'

2Fix

Restart with --force, or use package manager overrides instead of links.

npx vite --force

3Verify

Load the app after the restart.

curl -I http://localhost:5173

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

The cache in node_modules/.vite is stale

1Check

The cache is rebuilt when the lockfile, the patches folder, relevant config fields or NODE_ENV change. Delete the folder to force a rebuild if you suspect it is out of date.

ls -la node_modules/.vite

2Fix

Delete the cache folder and start again. In the browser, disable the cache in the Network tab while debugging.

rm -rf node_modules/.vite
npx vite

3Verify

Hard-reload the page and confirm the 504 is gone.

ls node_modules/.vite/deps

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Add lazily imported or plugin-created dependencies to optimizeDeps.include.
  • Restart with --force after changing a linked package.
  • Commit your lockfile so the cache invalidates when dependencies change.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.