vite-errors-build

name	vite-errors-build
description	Use when encountering Vite build failures, chunk size warnings, or version-specific build errors. Prevents the common mistake of using deprecated rollupOptions in v8 or misconfiguring build targets and minifiers. Covers Rolldown/Rollup bundling failures, CSS minification errors, sourcemap problems, library mode build failures, BundleError handling, and asset processing errors. Keywords: build error, Rolldown, chunk size, sourcemap, library mode, minify, BundleError, rollupOptions, build.target, build fails, vite build broken, chunk too large, production build error, output too big.
license	MIT
compatibility	Designed for Claude Code. Requires Vite 6.x, 7.x, or 8.x.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

vite-errors-build

Quick Reference: Build Error Diagnostic Table

Symptom	Cause	Fix
Could not resolve './module'	Unresolved import path	Check file exists, verify resolve.alias config, ensure extensions match resolve.extensions
Circular dependency detected	Modules import each other	Refactor shared logic into a third module; use dynamic import() to break the cycle
[vite]: Rollup failed to resolve import	Bare import not in node_modules	Run npm install, verify package name spelling, check optimizeDeps.include
Warning: Some chunks are larger than 500 KiB	Chunk exceeds build.chunkSizeWarningLimit	Code-split with dynamic imports, increase limit, or use build.rolldownOptions.output.manualChunks
build.target: Unexpected token	Syntax too modern for target browsers	Lower build.target (e.g., 'es2020') or add @vitejs/plugin-legacy
CSS minification error (v8)	Lightning CSS cannot parse CSS	Set build.cssMinify: 'esbuild' as fallback; fix invalid CSS syntax
Sourcemap is likely to be incorrect	Plugin transforms without sourcemap	Set build.sourcemap: false or fix plugin to emit sourcemaps
Missing "name" option for UMD export	Library mode UMD without name	Add build.lib.name: 'MyLib' for UMD/IIFE formats
build.rollupOptions is deprecated (v8)	Using Rollup config key in v8	Rename to build.rolldownOptions
BundleError thrown (v8)	Build API throws structured error	Catch with e.errors array iteration (see v8 Error Handling)
terser not found	Terser not installed	Run npm install -D terser; or switch to build.minify: 'oxc' (v8 default)
esbuild not found (v8)	esbuild no longer bundled in v8	Run npm install -D esbuild; or migrate to oxc config
Could not load content for ... (sourcemap)	Sourcemap references missing source	Set build.sourcemap: 'hidden' or ensure sources exist
vite:preloadError in browser	Dynamic import chunk missing after deploy	Listen for vite:preloadError event, trigger page reload
emptyOutDir: outDir is not inside root	Safety check prevents deletion	Pass build.emptyOutDir: true explicitly to override
assetsDir is ignored in lib mode	Library mode ignores build.assetsDir	ALWAYS use flat output or build.rolldownOptions.output.assetFileNames in lib mode
moduleType not set (v8 plugin)	Plugin transforms non-JS without declaring type	Add moduleType: 'js' in plugin load/transform hook return

---

Critical Warnings

NEVER ignore chunk size warnings in production -- they indicate bundles that degrade page load performance. ALWAYS code-split large vendor dependencies with dynamic imports.

NEVER set build.sourcemap: true in production without understanding the security implications -- sourcemaps expose original source code. Use 'hidden' to generate maps without embedding references.

NEVER use build.rollupOptions in Vite 8 -- it is deprecated and will be removed. ALWAYS use build.rolldownOptions instead.

ALWAYS install terser separately when using build.minify: 'terser' -- Vite does NOT bundle terser. In v8, esbuild is also not bundled.

ALWAYS handle vite:preloadError in SPAs to gracefully recover from stale chunk references after deployment.

---

Decision Tree: Build Failure Diagnosis

Build fails?
  |
  +-- Error message contains "resolve"?
  |     +-- Bare import? --> Check node_modules, run npm install
  |     +-- Relative import? --> Verify file path, check resolve.alias
  |     +-- TypeScript path? --> Enable resolve.tsconfigPaths or add alias
  |
  +-- Error message contains "chunk" or "size"?
  |     +-- Warning only? --> Split code or raise build.chunkSizeWarningLimit
  |     +-- Build fails? --> Check build.rolldownOptions.output config
  |
  +-- Error message contains "CSS"?
  |     +-- Lightning CSS error (v8)? --> Fallback to build.cssMinify: 'esbuild'
  |     +-- Preprocessor error? --> Check sass/less/stylus installed
  |     +-- PostCSS error? --> Verify postcss config, check plugin versions
  |
  +-- Error message contains "minify"?
  |     +-- terser not found? --> npm install -D terser
  |     +-- esbuild not found (v8)? --> npm install -D esbuild or use oxc
  |     +-- oxc error? --> Check oxc config syntax, report upstream if bug
  |
  +-- Error message contains "target"?
  |     +-- Syntax error in output? --> Lower build.target
  |     +-- CSS feature unsupported? --> Set build.cssTarget separately
  |
  +-- Library mode error?
  |     +-- Missing name? --> Add build.lib.name for UMD/IIFE
  |     +-- Missing externals? --> Add to build.rolldownOptions.external
  |     +-- CSS filename? --> Use build.lib.cssFileName
  |
  +-- v8 migration error?
        +-- rollupOptions? --> Rename to rolldownOptions
        +-- esbuild config? --> Rename to oxc config
        +-- moduleType error? --> Add moduleType: 'js' in plugin
        +-- BundleError? --> Catch e.errors array

---

v8 BundleError Handling

Vite 8 throws a BundleError from the build() API instead of raw errors. ALWAYS use structured error handling:

import { build } from 'vite'

try {
  await build()
} catch (e) {
  if (e.errors) {
    // BundleError: iterate structured error array
    for (const error of e.errors) {
      console.error(`[${error.code}] ${error.message}`)
      if (error.frame) console.error(error.frame)
      if (error.loc) {
        console.error(`  at ${error.loc.file}:${error.loc.line}:${error.loc.column}`)
      }
    }
  } else {
    // Fallback for non-BundleError
    throw e
  }
}

---

Chunk Size Optimization

Default warning limit: 500 KiB (uncompressed). To fix large chunks:

// Option 1: Dynamic imports for route-level code splitting
const AdminPanel = () => import('./views/AdminPanel.vue')

// Option 2: Manual chunk splitting (v8 with Rolldown)
export default defineConfig({
  build: {
    rolldownOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) {
            if (id.includes('lodash')) return 'vendor-lodash'
            if (id.includes('chart.js')) return 'vendor-charts'
            return 'vendor'
          }
        },
      },
    },
  },
})

// Option 3: Raise the limit (last resort)
export default defineConfig({
  build: {
    chunkSizeWarningLimit: 1000, // KiB
  },
})

NEVER raise chunkSizeWarningLimit without first attempting code splitting -- the warning exists to protect user experience.

---

vite:preloadError Recovery

After deployment, users with cached pages may request chunks that no longer exist. ALWAYS add this handler to SPA entry points:

// main.ts -- add BEFORE app initialization
window.addEventListener('vite:preloadError', (event) => {
  event.preventDefault()
  // Reload to fetch updated HTML with new chunk references
  window.location.reload()
})

---

emptyOutDir Safety

Vite refuses to empty outDir if it is outside the project root:

// outDir outside root triggers safety warning
export default defineConfig({
  build: {
    outDir: '../dist',           // Outside root -- Vite warns and skips
    emptyOutDir: true,           // Explicit override required
  },
})

ALWAYS set build.emptyOutDir: true explicitly when outDir is outside root. Vite adds this safety check to prevent accidental deletion of unrelated directories.

---

Version-Specific Error Patterns

Error Pattern	Vite 6	Vite 7	Vite 8
Bundler config key	build.rollupOptions	build.rollupOptions	build.rolldownOptions
Transform config	esbuild	esbuild	oxc
Default minifier	esbuild	esbuild	oxc
CSS minifier default	esbuild	esbuild	Lightning CSS
build.target default	'modules'	'baseline-widely-available'	'baseline-widely-available'
Build error type	Raw error	Raw error	BundleError
Plugin moduleType	Not required	Not required	Required for non-JS
Node.js minimum	18+	20.19+ / 22.12+	20.19+ / 22.12+

---

Reference Links

• references/error-catalog.md -- Complete build error catalog with symptom, cause, fix for every known pattern
• references/examples.md -- Reproducible error scenarios with step-by-step solutions
• references/anti-patterns.md -- Build configuration mistakes to avoid

Official Sources

• https://vite.dev/guide/build
• https://vite.dev/config/build-options
• https://vite.dev/guide/migration
• https://vite.dev/guide/dep-pre-bundling