Rollup manualChunks "Generated an empty chunk" / Circular Warnings

By Daniel Zoghalchali·Latchkey

A custom output.manualChunks assigned modules to a chunk in a way Rollup could not honor - producing an empty chunk, breaking the load order, or causing a circular-chunk warning. The chunking function is the cause, not your source.

What this error means

A vite build/rollup run warns Generated an empty chunk: "<name>", or emits chunks that fail to load in the browser (a vendor chunk importing the entry, or initialization-order errors). It surfaces only when manualChunks is configured.

(!) Generated an empty chunk: "vendor".
(!) Circular dependency: chunk "vendor" -> chunk "index" -> chunk "vendor"
rendering chunks...

Diagnose it: is it resolution, transform, or memory?

Bundler failures in CI fall into three families and the error text often points at the wrong one. A module that resolves on your machine and not on the runner is nearly always case sensitivity or a missing optional dependency; a transform error is a config or version mismatch; and an unexplained kill with no stack is the out-of-memory reaper, not a build error at all.

# 1. resolution: does the file exist with EXACTLY that case?
git ls-files | grep -i "the/imported/path"

# 2. transform: what versions is CI actually resolving?
npm ls webpack vite rollup esbuild typescript 2>/dev/null | head -20

# 3. memory: was it killed rather than failed?
#    exit 137 = SIGKILL (OOM). Nothing in the bundler log will explain it.
node --max-old-space-size=4096 node_modules/.bin/vite build

Common causes

A chunk name matches no real modules

A manualChunks branch returns a chunk name for a condition that never matches (or matched modules were tree-shaken away), so Rollup emits an empty chunk.

Mis-grouping creates a circular chunk graph

Putting modules that depend on the entry into a "vendor" chunk (or splitting a strongly-connected module group across chunks) creates circular chunk imports and load-order bugs.

How to fix it

Group only stable third-party modules

Restrict manualChunks to node_modules and return undefined for everything else so Rollup chunks the rest automatically.

// vite.config.ts
build: {
  rollupOptions: {
    output: {
      manualChunks(id) {
        if (id.includes('node_modules')) return 'vendor'
        // return undefined -> let Rollup decide
      },
    },
  },
}

Remove names that match nothing

1. For each empty-chunk warning, find the manualChunks branch producing that name.
2. Delete the branch or fix its condition so it only fires for modules that exist.
3. Avoid putting first-party modules that import the entry into a vendor chunk.

Make the build reproducible before you debug it

• Pin the Node major in setup-node and in engines. A bundler that resolves native bindings will pick a different prebuilt binary across majors.
• Delete node_modules locally and reinstall from the lockfile before concluding the runner is at fault; most "works locally" reports are stale local state.
• Set CI=true locally to reproduce. Several toolchains change behaviour under it, including treating warnings as errors.
• Exit code 137 is an out-of-memory kill. Raise --max-old-space-size or move to a larger runner rather than searching the bundler config.

How to prevent it

• Keep manualChunks limited to node_modules vendor splitting.
• Return undefined for modules you want Rollup to chunk automatically.
• Treat empty-chunk and circular-chunk warnings as build errors in CI.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation