Fix Vite Dependency Optimization Failed: Cache Corruption and Recovery

Quick Answer

• Root cause: Vite's dependency pre-bundling cache (.vite directory) becomes stale or corrupted after dependency updates, configuration changes, or version mismatches, causing chunk-file-not-found errors on dev server startup.
• First check: Stop all running Vite processes, then run rm -rf node_modules .vite && yarn to fully clear both package installs and pre-bundle cache.
• Minimal fix: rm -rf .vite && npx vite --force rebuilds only the pre-bundle cache without reinstalling packages—try this first if you're confident dependencies are correct.
• Persistent workaround: Add optimizeDeps.exclude: ['problem-package'] in vite.config.js to skip pre-bundling for specific packages identified in the error message.
• Version boundary: This issue affects Vite 2.x through 5.x; the fix applies to all versions. Production builds (vite build) are rarely affected.

What Problem It Solves

Vite uses dependency pre-bundling to convert CommonJS/UMD dependencies into ESM and improve dev server startup performance. The pre-bundled output is cached in <project-root>/.vite/deps/. When this cache becomes inconsistent—due to package updates, lockfile changes, or Vite configuration changes—the dev server fails with errors like:

The file does not exist at "/node_modules/.vite/deps/chunk-*.js"
ENOENT: no such file or directory, unlink '/node_modules/.vite/deps/...'
Failed to resolve entry for package "package-name"

This guide provides a structured recovery process, from quick cache clearing to permanent configuration fixes.

Root Cause Analysis

Vite's dependency optimizer runs during vite dev startup. It:

1. Scans your entry points for bare imports (e.g., import React from 'react')
2. Pre-bundles those dependencies into optimized ESM chunks
3. Writes the output to .vite/deps/ with a metadata file tracking versions and hashes

Cache corruption happens when:

• Lockfile changes: yarn.lock or package-lock.json updates without clearing .vite
• Partial installs: yarn install --frozen-lockfile fails silently, leaving stale cache
• Vite config changes: Modifying optimizeDeps.include or optimizeDeps.exclude without cache invalidation
• Concurrent processes: Multiple Vite instances writing to the same .vite directory
• File system locks: Windows processes holding handles on .vite files during deletion

The error chunk-*.js not found specifically means the metadata file references chunk filenames that no longer exist on disk—a classic cache inconsistency.

Minimal Working Configuration

Quick Recovery (No Config Changes)

BASH
# Stop all Vite processes first
# Then clear only the pre-bundle cache
rm -rf .vite

# Restart with force rebuild
npx vite --force

Full Recovery (Recommended)

BASH
# Complete clean: packages + cache
rm -rf node_modules .vite

# Reinstall and rebuild
yarn

# Start dev server with force rebuild
npx vite --force

Persistent Fix via vite.config.js

When clearing cache doesn't help, or the error recurs, identify the problematic package from the error message and exclude it from pre-bundling:

JS
// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    exclude: ['package-name-that-fails']
  }
})

If the error mentions multiple packages, exclude them all:

JS
optimizeDeps: {
  exclude: ['react-router-dom', 'date-fns', 'some-other-lib']
}

Parameters and Environment Variables

Common Errors and Fixes

Production Notes and Security Checks

• Development only: This issue and its fixes apply exclusively to vite dev. Production builds (vite build) do not trigger dependency pre-bundling and are unaffected.
• CI/CD impact: Running rm -rf node_modules .vite in CI pipelines forces a full dependency download on every build, increasing build time. Consider using rm -rf .vite alone if packages are cached by the CI system.
• Windows considerations: On Windows, node_modules may be locked by running processes. Use taskkill /F /IM node.exe before deletion, or use npx rimraf node_modules .vite instead of rm -rf.
• Team consistency: If multiple developers encounter this, ensure everyone uses the same lockfile and Vite version. Add .vite to .gitignore (it should already be there by default).
• Security: Clearing node_modules requires write permissions to the project directory. In shared environments, ensure proper file permissions.

FAQ

Q: Why does clearing node_modules and .vite cache fix most issues?

A: Vite's pre-bundling cache (.vite) stores optimized chunks keyed to specific dependency versions. When packages are updated or lockfiles change, the cache references stale chunk files. Clearing both node_modules (to get fresh packages) and .vite (to remove stale cache) guarantees a clean state where all dependencies are re-downloaded and re-pre-bundled from scratch. This eliminates corruption from partial updates, version mismatches, or incomplete installs.

Q: Does using optimizeDeps.exclude affect performance?

A: Yes. Excluded packages are served as raw ESM or CommonJS to the browser without pre-bundling. This means the browser must resolve and parse them individually, which can slow initial page loads—especially for large libraries. Additionally, some packages rely on Vite's CommonJS-to-ESM conversion during pre-bundling; excluding them may cause runtime errors. Use exclude only as a targeted workaround for specific failing packages, and prefer cache clearing as the primary fix.

Q: Does this solution apply to production builds?

A: No. The dependency optimization error occurs only during vite dev startup. Production builds (vite build) use Rollup for bundling and do not run the pre-bundling optimizer. If you encounter similar errors during vite build, the cause is likely a different issue—such as missing plugins, incompatible package versions, or incorrect build configuration—and requires separate debugging.