Troubleshooting Cookbook

Classify First

Do not start by deleting node_modules. First identify the stage, or you may erase the evidence.

0. Minimal Reproduction Info

Collect:

node -v
pnpm -v
pnpm vite --version
pnpm vite --debug

Also note the OS, package manager, lockfile state, monorepo/WSL/Docker/remote-container usage, HTTPS/proxy/port-forwarding, and whether dev or build fails.

1. Dev Server Requests Stay Pending

Check file descriptor limits, inotify limits, browser tabs, and custom middleware. Then run:

pnpm vite --debug

Common middleware bug:

configureServer(server) {
  server.middlewares.use((req, res, next) => {
    if (req.url?.startsWith("/api")) {
      res.end("ok")
      return
    }
    // missing next()
  })
}

Fix:

configureServer(server) {
  server.middlewares.use((req, res, next) => {
    if (req.url?.startsWith("/api")) {
      res.end("ok")
      return
    }
    next()
  })
}

2. HMR Detects Changes but Does Not Update

DEBUG=vite:hmr pnpm dev

Do not return an empty array casually from handleHotUpdate; it means no module should be updated.

3. Dev Works, Build Is Blank

Always reproduce production locally:

pnpm build
pnpm preview

Then check console errors, JS/CSS/chunk 404s, base, uploaded assets/, HTML cache, and browser extensions.

If the app is deployed under /app/, configure:

export default defineConfig({
  base: "/app/",
})

Long-cached HTML is another common cause. Old HTML points to chunks that no longer exist.

4. Dynamic Import Fails

Failed to fetch dynamically imported module

Use the Network panel:

• Is the URL missing the deployment sub-path?
• Does the chunk exist on the server?
• Is the response actually an HTML 404 page?
• Is a Service Worker caching old files?
• Did the CDN update HTML but not assets?

For broad dynamic imports, prefer import.meta.glob:

const pages = import.meta.glob("./pages/*.tsx")
const page = pages[`./pages/${name}.tsx`]

5. Optimized Dependencies Are Stale

Symptoms: startup refresh, linked package stale, or dependencies optimize every run.

DEBUG=vite:deps pnpm dev
pnpm vite --force

If it keeps happening, fix the cause:

6. Node Module Externalized in Browser

Module "fs" has been externalized for browser compatibility

This means browser code imported a Node built-in. Vite does not automatically polyfill fs, path, or crypto.

Check whether the code should run in the browser, split server-only code, replace it with Web APIs, or choose a browser-compatible package. Avoid adding broad polyfills unless you understand the bundle cost.

7. Plugin Missing or Slow

For missing plugins, check plugins, apply, enforce, filters, and whether the hook only runs in build.

For slow transforms:

• Use Vite DevTools for plugin timing
• Use vite-plugin-inspect for a single module transform chain
• Add timing to resolveId, load, and transform

Most plugin performance bugs come from overly broad filters, not a single slow line.

8. ESM/CJS Config Problems

Prefer ESM config:

import { defineConfig } from "vite"

export default defineConfig({})

If an ESM-only package is loaded through require(), use ESM syntax, set "type": "module" if appropriate, upgrade old plugins, and avoid mixing require() with ESM-only dependencies in Vite config.

Recommended Flow

1. Reproduce: dev, build, or preview?
2. Classify: config / dev server / HMR / deps / build / plugin
3. Enable the matching debug logs
4. Narrow to one module, plugin, chunk, or request
5. Make one minimal fix
6. Verify with build + preview

Change one variable at a time.

Check Yourself

1. Why start HMR debugging with DEBUG=vite:hmr?
2. How do you decide if a dynamic import failure is code or deployment?
3. What does --force fix, and why should it not be permanent?
4. What is the right order for browser-side Node externalization warnings?

# A project works in dev but sometimes blanks after deployment.
# Console shows Failed to fetch dynamically imported module.
# CDN has long cache enabled.
# Write your debugging order and likely fix.