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

By Daniel Zoghalchali·Latchkey

The Node process running the build exhausted V8's heap and aborted. Large bundles, source maps, and many 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, often after running a while. It may pass locally on a bigger machine and fail on a smaller runner.

<--- 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 / 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 developer laptop would not.

How to fix it

Raise Node's heap limit

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

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

1. Use cheaper source maps in CI (e.g. source-map only where needed) or disable them for the failing step.
2. Split vendor code and lazy-load routes so fewer modules are in memory at once.
3. Use a bigger runner for the build job 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.
• Keep bundles lean with code-splitting and modest source-map settings.

Frequently asked questions

Related guides

References

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