Vite Errors Build

vite-errors-build

Quick Reference: Build Error Diagnostic Table

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

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