Vite "JavaScript heap out of memory" on Large App Builds in CI

By Kaveh Alemi·Latchkey

A large vite build runs Rollup over thousands of modules, and the Node process can exhaust V8's heap on a constrained runner. It aborts with the same OOM as any other Node build.

What this error means

vite build dies with FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory, usually late in the production Rollup pass, on a runner with less RAM than your laptop.

transforming...
✓ 3120 modules transformed.
rendering chunks...
<--- Last few GCs --->
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

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

Heap default too low for a big Rollup pass

Many modules, large source maps, and heavy chunking inflate peak memory beyond V8's default old-space cap.

Constrained CI runner

A small runner or container memory cap gives Node less RAM than the build peak, so it OOMs where a bigger machine would not.

How to fix it

Raise Node's heap and trim source maps

Give V8 more old-space and reduce source-map cost for the build.

export NODE_OPTIONS=--max-old-space-size=4096
vite build
# vite.config.ts: build: { sourcemap: false } // or 'hidden' in CI

Split chunks and lazy-load routes

1. Use build.rollupOptions.output.manualChunks to break up large vendor chunks.
2. Lazy-load routes/components so fewer modules render at once.
3. Run the build on a larger runner for genuinely large apps.

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

• Set a sensible --max-old-space-size for the build job.
• Trim source maps and split chunks to lower peak memory.
• Faster managed runners such as Latchkey offer more RAM plus dependency caching so large Vite builds complete under the heap ceiling and transient OOMs are auto-retried.

Frequently asked questions

Related guides

References

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