Node.js "JavaScript heap out of memory" in CI - Fix FATAL Heap Errors

Node’s V8 engine has a default heap ceiling. Large builds - webpack, tsc, big test runs - can exceed it and abort with a fatal heap error.

What this error means

The process aborts with a FATAL ERROR mentioning the heap limit, often after a long build. If the OS OOM killer gets there first you may instead see exit code 137 with just Killed.

Build output

<--- Last few GCs --->
FATAL ERROR: Reached heap limit Allocation failed -
JavaScript heap out of memory
 1: 0xb... node::Abort()

Common causes

Default V8 heap limit is too low for the build

Bundlers and the TypeScript compiler can hold large graphs in memory. On a default heap, a big project crosses the limit and V8 aborts.

The runner itself is low on memory

Raising the heap limit above the physical memory just moves the failure to the OS OOM killer (exit 137). The heap limit and the runner memory must both be sufficient.

How to fix it

Raise the V8 heap limit

Set --max-old-space-size (in MB) below the runner’s available memory.

Terminal / workflow

# one-off
NODE_OPTIONS=--max-old-space-size=4096 npm run build

# in a workflow
env:
  NODE_OPTIONS: --max-old-space-size=4096

Reduce peak memory

Lower test parallelism (Jest --maxWorkers=2).
Disable or reduce source maps in CI builds.
Split a giant build into smaller package/workspace builds.

How to prevent it

Set NODE_OPTIONS heap limit relative to runner memory in CI.
Use a runner with enough RAM for the build.
Track build memory so growth is caught early.

Frequently asked questions

What is the difference between this and exit code 137?

This fatal heap error is V8 hitting its own configured limit and aborting cleanly with a message. Exit 137 is the OS killing the process with SIGKILL - usually because it exceeded the runner’s memory. Raising the heap limit too high converts the first into the second.