---
# === IDENTITY ===
id: software/debugging/webpack-vite-build-failures/2026
canonical_question: "How do I debug Webpack and Vite build failures?"
aliases:
  - "Webpack build error fix"
  - "Vite build failure troubleshooting"
  - "Webpack module not found error"
  - "Vite module resolution error"
  - "Webpack 5 build failure"
  - "Vite production build error"
  - "Webpack loader error"
  - "Vite rollup build error"
entity_type: software_reference
domain: software > debugging > webpack_vite_build_failures
region: global
jurisdiction: global
temporal_scope: 2020-2026

# === VERIFICATION ===
last_verified: 2026-05-17
confidence: 0.93
version: 1.1
first_published: 2026-02-20

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: evolving
  last_breaking_change: "Vite 8.0 (2025-12) made Rolldown the default bundler, replaced esbuild with Oxc for JS transforms, switched CSS minification to Lightning CSS, removed 'system'/'amd' output formats, and changed CJS default-import interop"
  next_review: 2026-11-13
  change_sensitivity: high

# === AGENT HINTS ===
inputs_needed:
  - key: bundler
    question: "Which bundler are you using: Webpack or Vite?"
    type: choice
    options: ["Webpack", "Vite", "Both"]
  - key: error_type
    question: "What type of error are you seeing?"
    type: choice
    options: ["Module not found", "Loader/plugin error", "Build hangs or OOM", "Runtime error after build", "Other"]

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/software/debugging/webpack-vite-build-failures/2026"
suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-05-17)"

# === RELATED UNITS ===
constraints:
  - "Covers Webpack 4+/5+ and Vite 4+/5+/6+/7+/8+ only — does not apply to standalone Rollup, esbuild, Parcel, or Turbopack builds"
  - "Webpack 5 requires Node.js >= 10.13.0; Vite 7+ requires Node.js >= 20.19 or >= 22.12 (Node 18 dropped); Vite 8 keeps the same Node baseline — verify runtime version before applying any fix"
  - "ESM/CJS guidance assumes the project uses a single bundler config — monorepos with mixed bundler configs may need per-package resolution"
  - "Node.js polyfill fallback advice (resolve.fallback) applies only to browser targets — has no effect when Webpack target is 'node' or 'electron-main'"
  - "Platform-specific binary fixes (Rollup/esbuild/Rolldown native binaries) assume npm or pnpm — Yarn PnP uses a different resolution mechanism; Vite 8 ships Rolldown by default so the missing binary is now '@rolldown/binding-*' not '@rollup/rollup-*'"
skip_this_unit_if:
  - condition: "Error occurs during npm/yarn/pnpm install, not during build"
    use_instead: "software/debugging/npm-dependency-conflicts/2026 — npm Dependency Conflicts"
  - condition: "Error is a TypeScript type error (TS2304, TS2345, etc.) not a bundler module-resolution or loader error"
    use_instead: "software/debugging/typescript-compilation-errors/2026 — TypeScript Compilation Errors"
  - condition: "Using standalone Rollup, esbuild, or Turbopack without a Webpack or Vite wrapper"
    use_instead: "The bundler's own troubleshooting docs (rollupjs.org, esbuild.github.io, turbo.build)"
  - condition: "Error is a runtime exception in the browser (e.g., Uncaught ReferenceError) after a successful build"
    use_instead: "Browser DevTools debugging guides or framework-specific runtime error documentation"
related_kos:
  related_to:
    - id: "software/debugging/npm-dependency-conflicts/2026"
      label: "npm Dependency Conflicts"
    - id: "software/debugging/typescript-compilation-errors/2026"
      label: "TypeScript Compilation Errors"
    - id: "software/debugging/nextjs-build-failures/2026"
      label: "Next.js Build Failures"
  often_confused_with:
    - id: "software/debugging/npm-dependency-conflicts/2026"
      label: "npm Dependency Conflicts (install-time 'ERESOLVE' errors, not build-time 'Module not found')"
    - id: "software/debugging/typescript-compilation-errors/2026"
      label: "TypeScript Compilation Errors (TS type errors vs bundler loader/resolution errors)"
    - id: "software/debugging/nextjs-build-failures/2026"
      label: "Next.js Build Failures (framework-level Webpack/Turbopack wrapper errors vs raw Webpack/Vite config)"

# === SOURCES (9 authoritative sources) ===
sources:
  - id: src1
    title: "Troubleshooting | Vite"
    author: Vite Team
    url: https://vite.dev/guide/troubleshooting
    type: official_docs
    published: 2025-12-01
    reliability: authoritative
  - id: src2
    title: "To v5 from v4 | webpack"
    author: webpack Contributors
    url: https://webpack.js.org/migrate/5/
    type: official_docs
    published: 2024-01-01
    reliability: authoritative
  - id: src3
    title: "Build Performance | webpack"
    author: webpack Contributors
    url: https://webpack.js.org/guides/build-performance/
    type: official_docs
    published: 2024-01-01
    reliability: authoritative
  - id: src4
    title: "Troubleshooting — SurviveJS Webpack"
    author: SurviveJS
    url: https://survivejs.com/books/webpack/appendices/troubleshooting/
    type: technical_blog
    published: 2024-06-01
    reliability: high
  - id: src5
    title: "Building for Production | Vite"
    author: Vite Team
    url: https://main.vitejs.dev/guide/build.html
    type: official_docs
    published: 2025-12-01
    reliability: authoritative
  - id: src6
    title: "How To Fix Unhandled Exception Cannot Find Module Webpack"
    author: Squash.io
    url: https://www.squash.io/how-to-fix-unhandled-exception-cannot-find-module-webpack/
    type: technical_blog
    published: 2024-08-01
    reliability: moderate_high
  - id: src7
    title: "Fixing Vite Build Error: Cannot find module @rollup/rollup-linux-x64-musl"
    author: Dulal Sandip
    url: https://sandipdulal.medium.com/fixing-vite-build-error-on-linux-and-windows-using-docker-error-cannot-find-module-e73bb2fb479d
    type: technical_blog
    published: 2024-09-01
    reliability: moderate_high
  - id: src8
    title: "Migration from v7 | Vite"
    author: Vite Team
    url: https://vite.dev/guide/migration
    type: official_docs
    published: 2025-12-01
    reliability: authoritative
  - id: src9
    title: "Roadmap 2026 | webpack"
    author: webpack Contributors
    url: https://webpack.js.org/blog/2026-02-04-roadmap-2026/
    type: official_docs
    published: 2026-02-04
    reliability: authoritative
---

# How Do I Debug Webpack and Vite Build Failures?

## TL;DR

- **Bottom line**: Most Webpack and Vite build failures fall into 5 categories: **module not found** (wrong path or missing install), **loader/plugin misconfiguration** (wrong version or missing config), **Node.js polyfill removal** (Webpack 5 dropped automatic polyfills), **ESM/CJS mismatch** (wrong module format), and **platform-specific binary issues** (Rollup native binaries in Vite). Systematically check error messages, validate `node_modules`, and use verbose/debug flags to isolate the cause. [src1, src2, src4]
- **Key tool/command**: `npx webpack --stats=verbose` (Webpack) or `vite build --debug` (Vite) -- verbose output reveals the exact file, loader, or plugin causing the failure. [src3, src4]
- **Watch out for**: Webpack 5 silently removes Node.js core module polyfills (`Buffer`, `process`, `crypto`, `path`). Code that worked in Webpack 4 will fail at runtime without explicit polyfill configuration. [src2]
- **Works with**: Webpack 4+/5+ (Node.js 10.13+; 5.106 current as of 2026-04, Webpack 6 still in preparation [src9]), Vite 4–6 (Node.js 18+) and Vite 7+/8+ (Node.js 20.19+ or 22.12+; Vite 8 defaults to Rolldown bundler). [src2, src1, src8, src9]

## Constraints
<!-- Agents: read this section before recommending any action from this unit.
     These are hard constraints that must not be violated. -->

- **Never blindly delete `node_modules` and reinstall** without first reading the error message -- this wastes time and may mask the real issue. Only clean-reinstall when lockfile corruption or phantom dependencies are suspected. [src4, src6]
- **Webpack 5 requires Node.js >= 10.13.0**; Vite 6 requires Node.js >= 18; Vite 7+ requires Node.js >= 20.19 or >= 22.12 (Node 18 EOL'd). Always verify the runtime version before debugging build errors. [src2, src1, src8]
- **Do not mix ESM and CJS config formats** without explicit handling. Webpack uses `webpack.config.js` (CJS by default); Vite uses `vite.config.js` (ESM by default). Mismatched `"type": "module"` in `package.json` causes silent failures. [src1, src2]
- **Never add Node.js polyfills to a browser bundle without understanding the bundle size impact**. Each polyfill (`crypto-browserify`, `buffer`, `stream-browserify`) adds 50-200 KB. Prefer browser-native APIs instead. [src2]
- **Platform-specific native binaries** (Rollup/esbuild in Vite) must match the deployment OS. Cross-platform lockfiles generated on macOS will fail on Linux CI. [src1, src7]

## Quick Reference

| # | Error Pattern | Bundler | Likelihood | Signature | Fix |
|---|---|---|---|---|---|
| 1 | Module not found (import path) | Both | ~30% of cases | `Module not found: Can't resolve './Foo'` | Fix import path casing; verify file exists [src4, src6] |
| 2 | Module not found (package) | Both | ~20% | `Cannot find module 'lodash'` | `npm install lodash` or check `package.json` [src6] |
| 3 | Node.js polyfill missing | Webpack 5 | ~15% | `Module not found: Can't resolve 'crypto'` | Add `resolve.fallback` in webpack config or install `crypto-browserify` [src2] |
| 4 | Loader not found / misconfigured | Webpack | ~10% | `Module build failed: Unknown word` or `Can't resolve 'babel-loader'` | Install loader: `npm i -D babel-loader`; check `module.rules` config [src4] |
| 5 | ESM/CJS mismatch | Both | ~8% | `ERR_REQUIRE_ESM` or `SyntaxError: Cannot use import statement` | Add `"type": "module"` to `package.json` or rename config to `.mjs` [src1, src2] |
| 6 | Platform-specific binary missing | Vite | ~5% | `Cannot find module '@rollup/rollup-linux-x64-musl'` (Vite ≤7) or `@rolldown/binding-linux-x64-gnu` (Vite 8+) | Delete lockfile + `node_modules`, reinstall on target platform [src1, src7, src8] |
| 7 | JSON named import (Webpack 5) | Webpack 5 | ~3% | `export 'version' was not found in './package.json'` | Use default import: `import pkg from './pkg.json'` then `pkg.version` [src2] |
| 8 | Strict mode violation | Vite | ~3% | `SyntaxError: With statements cannot be used in strict mode` | Patch dependency via `pnpm patch` or `patch-package` [src1] |
| 9 | Chunk load failure (deploy) | Vite | ~3% | `Failed to fetch dynamically imported module` | Serve old chunks during rollover; add `vite:preloadError` handler [src1, src5] |
| 10 | Out of memory | Both | ~3% | `FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory` | `NODE_OPTIONS=--max-old-space-size=8192` [src3] |

## Decision Tree

> Full script: [decision-tree.txt](scripts/decision-tree.txt) (34 lines)

```
START — Build fails
├── Error message contains "Module not found" or "Can't resolve"?
│   ├── Points to a local file (./src/foo)?
│   │   ├── YES → Check file exists, verify casing (Linux is case-sensitive) [src4, src6]
│   │   └── NO → Points to a package?
# ... (see full script)
```

## Step-by-Step Guide

### 1. Read the full error message and enable verbose output

Most build errors include a clear description of what went wrong. Enable verbose/debug output to get complete context. [src3, src4]

```bash
# Webpack — enable detailed error info
npx webpack --stats=verbose

# Or add to webpack.config.js:
# module.exports = { stats: { errorDetails: true } }

# Vite — enable debug logging
npx vite build --debug

# Trace Node.js deprecation warnings (useful for loader issues)
node --trace-deprecation node_modules/.bin/webpack --mode production
```

**Verify**: Error output should now show file paths, loader chain, and resolution attempts.

### 2. Check Node.js and bundler versions

Version mismatches are a common hidden cause. [src2, src1]

```bash
# Check Node.js version
node --version
# Webpack 5 requires >= 10.13.0; Vite 6 requires >= 18

# Check bundler versions
npx webpack --version
npx vite --version

# Check for outdated dependencies
npm outdated
```

**Verify**: Versions match the minimum requirements for your config.

### 3. Validate module resolution

For "Module not found" errors, trace how the bundler resolves imports. [src4, src6]

```bash
# List installed packages (check if module exists)
npm list module-name

# Verify file exists with correct casing (critical on Linux)
ls -la src/components/MyComponent.js

# Webpack — trace resolution (add to config temporarily)
# resolve: { plugins: [new (require('enhanced-resolve').ResolverFactory)({
#   log: console.log })] }

# Clear caches (both bundlers)
rm -rf node_modules/.cache
rm -rf node_modules/.vite
```

**Verify**: `npm list module-name` shows the package at the expected version.

### 4. Fix Webpack 5 Node.js polyfill errors

When migrating from Webpack 4, add explicit polyfill configuration. [src2]

```javascript
// webpack.config.js — Webpack 5 polyfill fallbacks
module.exports = {
  resolve: {
    fallback: {
      // Only add polyfills you actually need (each adds bundle size)
      "crypto": require.resolve("crypto-browserify"),
      "stream": require.resolve("stream-browserify"),
      "buffer": require.resolve("buffer/"),
      "path": require.resolve("path-browserify"),
      "os": require.resolve("os-browserify/browser"),
      // Set to false if module is not needed in browser
      "fs": false,
      "net": false,
      "tls": false,
    }
  },
  plugins: [
    // Provide global polyfills
    new (require('webpack')).ProvidePlugin({
      Buffer: ['buffer', 'Buffer'],
      process: 'process/browser',
    }),
  ]
};
```

```bash
# Install required polyfill packages
npm install --save-dev crypto-browserify stream-browserify buffer path-browserify os-browserify process
```

**Verify**: `npx webpack` completes without "Can't resolve 'crypto'" errors.

### 5. Fix Vite ESM and platform issues

Resolve common Vite-specific build failures. [src1, src7]

```javascript
// vite.config.js — common fixes
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    // Target older browsers if needed
    target: 'es2015',
    // Increase chunk size warning limit (default 500 KB)
    chunkSizeWarningLimit: 1000,
    // Fix publicPath issues
    // base: '/my-app/',
  },
  optimizeDeps: {
    // Force re-optimization after linking packages
    force: true,
    // Include problematic CJS dependencies
    include: ['problematic-cjs-package'],
  },
  resolve: {
    // Fix case sensitivity issues
    preserveSymlinks: false,
  },
});
```

```bash
# Force Vite to re-optimize dependencies
npx vite --force

# Fix platform-specific binary issues (CI/Docker)
rm -rf node_modules package-lock.json
npm install

# Profile build performance
npx vite build --profile
# Opens vite-profile-0.cpuprofile in speedscope.app
```

**Verify**: `npx vite build` completes without errors; inspect `dist/` output.

### 6. Fix loader and plugin configuration (Webpack)

Resolve loader chain errors by validating the config structure. [src3, src4]

```javascript
// webpack.config.js — correct loader configuration
const path = require('path');

module.exports = {
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        // CRITICAL: always scope loaders to your source
        include: path.resolve(__dirname, 'src'),
        use: {
          loader: 'babel-loader', // NOT 'babel' — use full name
          options: {
            presets: ['@babel/preset-env', '@babel/preset-react'],
            // Enable caching for faster rebuilds
            cacheDirectory: true,
          },
        },
      },
      {
        test: /\.css$/,
        // Order matters: loaders execute right-to-left
        use: ['style-loader', 'css-loader'],
      },
      {
        // Webpack 5 Asset Modules (replaces file-loader, url-loader, raw-loader)
        test: /\.(png|jpg|gif|svg)$/,
        type: 'asset/resource', // NOT use: 'file-loader'
      },
    ],
  },
  resolve: {
    extensions: ['.js', '.jsx', '.ts', '.tsx', '.json'],
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
  // Enable persistent cache for faster rebuilds
  cache: {
    type: 'filesystem',
  },
};
```

**Verify**: `npx webpack --stats=errors-only` returns zero errors.

## Code Examples

### JavaScript: Webpack 5 config with common error prevention

> Full script: [javascript-webpack-5-config-with-common-error-prev.js](scripts/javascript-webpack-5-config-with-common-error-prev.js) (34 lines)

```javascript
// Input:  webpack.config.js — production-ready configuration
// Output: Bundle with polyfill fallbacks, optimized loaders, filesystem cache
const path = require('path');
const webpack = require('webpack');
module.exports = {
# ... (see full script)
```

### JavaScript: Vite config with common error prevention

> Full script: [javascript-vite-config-with-common-error-preventio.js](scripts/javascript-vite-config-with-common-error-preventio.js) (27 lines)

```javascript
// Input:  vite.config.js — production-ready configuration
// Output: Optimized build with CJS compatibility and error handling
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
# ... (see full script)
```

### Bash: Automated build failure diagnostic script

> Full script: [bash-automated-build-failure-diagnostic-script.sh](scripts/bash-automated-build-failure-diagnostic-script.sh) (38 lines)

```bash
#!/bin/bash
# Input:  Run in project root with package.json
# Output: Diagnostic report for Webpack/Vite build failures
echo "=== Build Failure Diagnostic ==="
echo "Node: $(node --version) | npm: $(npm --version)"
# ... (see full script)
```

## Anti-Patterns

### Wrong: Adding all Node.js polyfills in Webpack 5

```javascript
// webpack.config.js
// BAD — polyfilling everything adds 500KB+ to your bundle [src2]
const NodePolyfillPlugin = require('node-polyfill-webpack-plugin');
module.exports = {
  plugins: [new NodePolyfillPlugin()],
};
// Adds crypto, stream, buffer, path, os, etc. even if unused
```

### Correct: Only polyfill what you actually need, or set to false

```javascript
// webpack.config.js
// GOOD — explicit fallbacks, unused modules set to false [src2]
module.exports = {
  resolve: {
    fallback: {
      "crypto": false, // not needed in browser
      "stream": require.resolve("stream-browserify"), // only if needed
      "fs": false,
      "path": false,
    }
  }
};
```

### Wrong: Not scoping loaders with include

```javascript
// webpack.config.js
// BAD — processes ALL .js files including node_modules [src3]
module.exports = {
  module: {
    rules: [{
      test: /\.js$/,
      loader: 'babel-loader', // transpiles thousands of node_modules files
    }],
  },
};
```

### Correct: Scope loaders to source directory

```javascript
// webpack.config.js
// GOOD — only transpile your own code [src3]
const path = require('path');
module.exports = {
  module: {
    rules: [{
      test: /\.js$/,
      include: path.resolve(__dirname, 'src'),
      loader: 'babel-loader',
      options: { cacheDirectory: true },
    }],
  },
};
```

### Wrong: Using require() for ESM-only packages in Vite config

```javascript
// vite.config.js
// BAD — ESM-only packages cannot be require()'d [src1]
const somePlugin = require('some-esm-only-plugin');
// Error: ERR_REQUIRE_ESM
```

### Correct: Use import or rename config to .mjs

```javascript
// vite.config.mjs (or add "type": "module" to package.json)
// GOOD — use ES module imports [src1]
import somePlugin from 'some-esm-only-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [somePlugin()],
});
```

### Wrong: Ignoring case sensitivity in imports

```javascript
// BAD — works on macOS/Windows, fails on Linux CI [src1, src6]
import MyComponent from './components/mycomponent'; // file is MyComponent.js
import utils from './Utils/helper'; // folder is utils/
```

### Correct: Match exact file and folder casing

```javascript
// GOOD — consistent casing matches filesystem [src1, src6]
import MyComponent from './components/MyComponent';
import utils from './utils/helper';
```

## Common Pitfalls

- **Webpack 5 `output.filename` using `[hash]`**: Deprecated in Webpack 5. Use `[contenthash]` instead -- it produces stable hashes that only change when file content changes, enabling better caching. Fix: Replace `[hash]` with `[contenthash]` in all output configs. [src2]
- **Vite `npm link` breaks pre-bundling**: Linked packages are not detected by Vite's dependency optimizer. Run `vite --force` to rebuild the dependency cache after linking. Fix: Prefer npm overrides or `pnpm` workspaces over `npm link`. [src1]
- **Webpack `Module parse failed` on CSS/SCSS**: Webpack does not natively understand CSS. You must add `css-loader` (and `style-loader` or `MiniCssExtractPlugin`). Fix: `npm i -D css-loader style-loader` and add the loader rule. [src4]
- **Vite chunk load failure after deployment**: When deploying new versions, old HTML pages reference stale chunk hashes that no longer exist. Fix: Add a `vite:preloadError` event listener to trigger a page reload, and keep old build files available briefly during rollover. [src1, src5]
- **Webpack `SplitChunks` cacheGroups renamed**: Webpack 5 renamed `vendors` to `defaultVendors`. Old configs silently create separate (unintended) chunk groups. Fix: Rename `cacheGroups.vendors` to `cacheGroups.defaultVendors`. [src2]
- **Cross-platform Rollup binary mismatch in Docker**: Package lockfiles generated on macOS include `@rollup/rollup-darwin-arm64` but Linux CI needs `@rollup/rollup-linux-x64-gnu`. Fix: Regenerate lockfile on the target platform, or delete lockfile before `npm install` in Docker. [src7]
- **Webpack cache invalidation after dependency changes**: Filesystem cache may serve stale transforms after updating `node_modules`. Fix: Add `"postinstall": "rm -rf node_modules/.cache"` to `package.json` scripts. [src3]
- **Vite 8 CJS default-import interop change**: Vite 8 unified dev and build behavior for default imports from CJS modules; some packages now return the full `module.exports` object instead of `module.exports.default`. Symptom: `TypeError: SomeImport is not a function` after upgrading. Fix: Update the import to use the named export, or temporarily set `legacy.inconsistentCjsInterop: true` in `vite.config.js` while you migrate. [src8]
- **Vite 8 plugins built for Rollup 4 may not load**: Vite 8 uses Rolldown + Oxc instead of Rollup + esbuild, and removed several plugin hooks. Symptom: `[plugin xxx] hook 'X' is not supported`. Fix: Upgrade to a Rolldown-compatible plugin version, or pin Vite to 7.x until the plugin is updated. [src8]

## Diagnostic Commands

> Full script: [diagnostic-commands.sh](scripts/diagnostic-commands.sh) (36 lines)

```bash
# === Webpack Diagnostics ===
# Verbose build output with error details
npx webpack --stats=verbose
# Only show errors (fast check)
npx webpack --stats=errors-only
# ... (see full script)
```

## Version History & Compatibility

| Version | Status | Key Changes | Migration Notes |
|---|---|---|---|
| Webpack 5.106 | Current (2026-04) | Native CSS (`experimental.css`) maturing; `tsconfig.json` path-resolution added in 5.105; universal target in progress; Webpack 6 in preparation | No upgrade required from earlier 5.x; track 2026 roadmap for breaking changes coming with 6.0 [src9] |
| Webpack 5.x | Stable since 2020-10 | Removed Node.js polyfills; Asset Modules replace file/url/raw-loader; persistent filesystem cache; `output.library.type` replaces `libraryTarget` | Run `npx codemod@latest webpack/v5/migration-recipe`; add `resolve.fallback` for Node.js modules [src2] |
| Webpack 4.x | Maintenance | Last version with automatic Node.js polyfills | Upgrade to 5.x; update all loaders/plugins first [src2] |
| Vite 8.x | Current (since 2025-12) | Rolldown bundler now default (replaces Rollup); Oxc replaces esbuild for JS transforms; Lightning CSS default for minification; CJS default-import interop changed; `'system'` and `'amd'` output formats removed | Test bundle size (Lightning CSS may slightly increase output); audit plugins for removed Rollup hooks; use `legacy.inconsistentCjsInterop: true` to restore old CJS interop temporarily [src8] |
| Vite 7.x | Previous stable (2025-06) | Optional Rolldown via `rolldown-vite` package; Node.js 20.19+ / 22.12+ baseline; Node 18 dropped | Upgrade Node first, then `npm install vite@7`; Rolldown still opt-in [src8] |
| Vite 6.x | Maintenance (2024-11) | Environment API introduced; Rolldown experimental | Check plugin compatibility with the Environment API [src1] |
| Vite 5.x | EOL | Rollup 4; Node.js 18+ required | Upgrade to 6.x → 7.x → 8.x in sequence [src1] |
| Vite 4.x | EOL | SWC support; improved ESM handling | Straightforward upgrade to 5.x [src1] |

## When to Use / When Not to Use

| Use This Guide When | Don't Use When | Use Instead |
|---|---|---|
| `npm run build` or `vite build` fails with errors | Dev server works but HMR is slow | Vite HMR troubleshooting or `server.watch` config |
| Migrating from Webpack 4 to 5 | Migrating from Webpack to Vite entirely | Vite migration guide |
| "Module not found" errors during build | Package install fails (`npm install` errors) | npm/yarn/pnpm dependency resolution guides |
| Runtime `process is not defined` after Webpack 5 upgrade | TypeScript type errors (not build errors) | TypeScript compilation error guides |
| CI build fails but local build works | Bundle too large (no errors, just size) | Webpack Bundle Analyzer or `vite-plugin-inspect` |

## Important Caveats

- **Webpack and Vite use fundamentally different architectures**: Webpack bundles everything through a loader pipeline; Vite serves native ESM in dev and uses Rollup (or Rolldown in v6) for production builds. A solution for one may not apply to the other. [src1, src2]
- **Vite's dev server and production build can behave differently**: Vite uses esbuild for dev dependency pre-bundling but Rollup for production bundling. Code that works in `vite dev` may fail in `vite build` due to different module resolution and tree-shaking behavior. [src1, src5]
- **Webpack 5 `resolve.fallback` only applies to the browser target**: If your target is Node.js (`target: 'node'`), webpack will resolve Node.js built-in modules natively and `fallback` has no effect. [src2]
- **`node_modules/.cache` can mask configuration changes**: Both Webpack filesystem cache and Vite pre-bundling cache may serve stale results after config changes. Clear caches when debugging unexpected behavior. [src3, src1]
- **Error messages may point to the wrong file**: Due to source maps and module concatenation, the file cited in an error may be a dependency rather than your code. Check the full stack trace and look for the first frame in your `src/` directory. [src4]

## Related Units

- [npm Dependency Conflicts](/software/debugging/npm-dependency-conflicts/2026)
- [TypeScript Compilation Errors](/software/debugging/typescript-compilation-errors/2026)
- [Next.js Build Failures](/software/debugging/nextjs-build-failures/2026)