webpack "JavaScript heap out of memory" - Fix Build OOM in CI

By Kaveh Alemi·Latchkey

The Node process running the webpack build exhausted V8's heap and aborted. Large bundles, source maps, and thousands of modules can exceed the default heap, especially on a small CI runner.

What this error means

The build dies with FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory, usually after running a while. It often passes on a developer laptop and fails on a smaller runner.

webpack

<--- Last few GCs --->
[1234:0x...] 60123 ms: Mark-sweep 2046.8 (2050.1) -> 2046.0 MB, ...
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
 1: 0xb09c10 node::Abort() ...

Common causes

Heap default too low for the build

V8's old-space cap can be lower than a big production build needs. Many modules, vendor chunks, and high-quality source maps all inflate peak memory.

Small runner or container memory limit

A constrained CI runner (or a 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 limit

Give V8 more old-space via NODE_OPTIONS so the build fits.

Terminal

export NODE_OPTIONS=--max-old-space-size=4096
npm run build
# package.json: "build": "node --max-old-space-size=4096 ./node_modules/.bin/webpack"

Shrink the build's memory footprint

Use cheaper source maps in CI, or disable them for the failing step.
Split vendor code and lazy-load routes so fewer modules are resident at once.
Run the build job on a bigger runner if the project is genuinely large.

How to prevent it

Set a sensible --max-old-space-size for the build job in CI.
Right-size the build runner to the project's real peak memory.
Faster managed runners such as Latchkey provide more RAM and dependency caching so heavy builds finish well under the heap ceiling and transient OOMs are auto-retried.

Frequently asked questions

What causes ""heap out of memory" (webpack)"?

V8's old-space cap can be lower than a big production build needs. Many modules, vendor chunks, and high-quality source maps all inflate peak memory.

How do I fix "heap out of memory" (webpack)?

Give V8 more old-space via NODE_OPTIONS so the build fits.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.