Fix: JavaScript heap out of memory (Node.js, tested)

Node gives JavaScript a fixed amount of memory, the heap limit. A big build, a large test run or a script that keeps too much in memory hits it, and the process dies with exit code 134:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

The limit isn’t your RAM. On my laptop with 11.8 GB, the default was:

You can check yours with node -e "console.log(require('v8').getHeapStatistics().heap_size_limit/2**20)".

Raising it is one setting, --max-old-space-size (in MB). How you pass it decides whether it actually reaches the process that runs out.

The fix: NODE_OPTIONS

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

"build": "cross-env NODE_OPTIONS=--max-old-space-size=4096 vite build"

Why the usual fix sometimes doesn’t work

Two surprises in the numbers

The limit you ask for isn’t the limit you get: --max-old-space-size=1024 gave a heap limit of 1,216 MB and =256 gave 448 MB. The flag sets the “old space”; Node adds its young generation on top.

Node also doesn’t check the number against your RAM. --max-old-space-size=100000 on this 11.8 GB laptop was accepted without a warning (limit: 100,192 MB). So a number above your RAM doesn’t fail fast; keep it below what the machine actually has.

How this was tested

Windows 11 Pro with 11.8 GB RAM, Node 24.14.0 and 26.11.1, npm 11.9.0, October 17, 2026. A script allocated arrays in a loop until it crashed or reached a set amount; the heap limit was read with v8.getHeapStatistics() in the script and in a child process it started with child_process. The npm script cases ran through npm run (which uses cmd.exe), cross-env 10.1.0, and PowerShell 5.1. Every message above is the real output.