Node "FATAL ERROR: Reached heap limit Allocation failed" in CI - Fix the OOM

This fatal error means V8 hit its heap limit and the garbage collector could not free enough memory, so the process aborts mid-build.

What this error means

A build (webpack, tsc, vite, jest) crashes in CI with FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory, then a V8 stack dump.

node

<--- Last few GCs --->
[1234:0x5a0] 41023 ms: Mark-sweep 2046.3 (2071.8) -> 2045.9 (2072.3) MB

<--- JS stacktrace --->
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Common causes

The default heap is too small for the build

Large bundlers and type-checks exceed the default V8 heap, especially on memory-constrained runners.

A memory leak or unbounded in-memory work

The build accumulates objects without releasing them, climbing until it hits the limit.

How to fix it

Raise the heap limit

Set NODE_OPTIONS to increase max-old-space-size for the build step.
Size it below the runner total memory.

GitHub Actions

- run: npm run build
  env:
    NODE_OPTIONS: --max-old-space-size=4096

Reduce build memory pressure

Split the build, limit parallelism, or trim source maps that balloon memory.

How to prevent it

Right-size max-old-space-size, profile build memory, and run memory-heavy builds on a larger managed runner. On Latchkey, larger managed runners give the build more headroom and transient OOM-kills are auto-retried.