JavaScript Heap Out of Memory in npm Build (CI) - Fix Fatal Heap Errors

V8 has a default heap ceiling. A large npm build (webpack, tsc, big test runs) can exceed it and abort with a fatal heap error before the build finishes.

What this error means

npm run build aborts with FATAL ERROR: Reached heap limit ... JavaScript heap out of memory, usually deep into a long build. If the OS kills it first you instead see exit 137.

npm

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

Common causes

The default V8 heap limit is too low for the build

Bundlers and the TypeScript compiler hold large graphs in memory; a big project crosses the default limit and V8 aborts.

The runner itself is low on memory

Raising the heap limit above physical RAM just trades the heap error for an OS OOM kill (exit 137).

How to fix it

Raise the V8 heap limit

Set NODE_OPTIONS max-old-space-size (MB) below the runner memory.
Re-run the build.

Workflow

env:
  NODE_OPTIONS: --max-old-space-size=4096

Reduce peak memory

Lower test parallelism and disable source maps in CI builds.
Split a giant build into smaller workspace builds.

How to prevent it

Set the heap limit relative to runner RAM and use a runner with enough memory. Latchkey self-healing managed runners detect an out-of-memory build and auto-retry transient OOM aborts on adequately sized capacity.