Fixing 'JavaScript Heap Out of Memory' Errors

If a Node process crashes with something like this, it's not a bug in your code — it's V8 (Node's JavaScript engine) hitting its default memory ceiling:

<--- Last few GCs --->
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

It shows up most often during large webpack/next build/tsc runs, big JSON parsing jobs, or processing large arrays without releasing references. Here's how to actually resolve it, not just paper over it.

Fix 1: raise V8's memory limit

By default, Node caps the old-generation heap at roughly 1.5–2 GB on 64-bit systems. Raise it explicitly:

node --max-old-space-size=4096 your-script.js

For an npm script (e.g. a build command), set it via NODE_OPTIONS so you don't have to edit the script itself:

NODE_OPTIONS="--max-old-space-size=4096" npm run build

4096 means 4 GB — pick a number comfortably under your machine's or CI runner's actual available RAM, not just a bigger number for its own sake.

Fix 2: find what's actually leaking

Raising the limit is a real fix when the workload is legitimately large (a big webpack bundle, a huge dataset). It's a band-aid if something is leaking — e.g. an array that keeps growing across requests, or event listeners that are never removed. Profile it before assuming it's just "not enough memory":

node --inspect --max-old-space-size=4096 your-script.js

Then open chrome://inspect in Chrome and take a heap snapshot. A snapshot that keeps growing between GC runs, rather than settling, points to a real leak worth fixing at the source.

Fix 3: for CI specifically

Most hosted CI runners (GitHub Actions included) have less memory than a typical dev laptop. If a build only fails in CI, set NODE_OPTIONS as a workflow environment variable rather than raising a limit that's already fine locally:

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

The short version

Set --max-old-space-size when the workload is genuinely big; profile with --inspect when the memory usage keeps climbing instead of leveling off — those are two different problems with two different fixes.