JavaScript heap out of memory (Node FATAL ERROR near heap limit)

V8 hit the ceiling it set for itself. The machine may still have free RAM — Node just refused to grow its JavaScript heap any further.

What the error looks like

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
 1: 0x… node::Abort() …
 2: 0x… v8::Utils::ReportOOMFailure …

Sometimes shortened to JavaScript heap out of memory in CI logs. It is a V8 abort, not a normal Error you can try/catch.

V8 heap vs system RAM

Default old-space is roughly 1.5–4 GB depending on Node version and whether the host looks "small". A 16 GB laptop can still throw heap OOM at ~2 GB because V8 never asked for more. Conversely, setting --max-old-space-size=8192 inside a 1 GB container will get you killed with 137 before V8 complains.

Raise the limit (when it is appropriate)

# One-off
node --max-old-space-size=4096 server.js
node --max-old-space-size=8192 ./node_modules/webpack/bin/webpack.js

# Sticky for child processes (npm scripts, CLIs)
export NODE_OPTIONS=--max-old-space-size=4096
npm run build

# package.json script
"build": "NODE_OPTIONS=--max-old-space-size=4096 next build"

• Values are megabytes. 4096 ≈ 4 GB.
• NODE_OPTIONS is inherited by anything that spawns node. Do not leave a huge value in a shared shell profile forever.
• Match the heap to ~50–75% of the container/VM memory so the process has room for native buffers, stacks and the OS.

When raising the limit is the wrong fix

• Memory leak — usage climbs over hours/days until crash. Restarting or bumping the heap only delays it. Take a heap snapshot (below).
• Huge JSON — JSON.parse of a multi-hundred-MB file doubles memory (string + object graph). Stream it (JSONStream, simdjson, line-delimited JSON) or process outside Node. Validate structure of smaller samples with the JSON formatter.
• webpack / CRA / Next build — giant dependency graphs, source maps, and Babel/TS transforms. Prefer: upgrade webpack 5 / Next, enable filesystem cache, split the build, build on a bigger machine/CI, or migrate CRA → Vite. Blindly setting 16 GB on a laptop hides the real cost.
• Loading entire files into strings — read streams, not fs.readFileSync of multi-GB inputs.

Chrome DevTools / heap snapshots (brief)

1. Run with inspect: node --inspect server.js (or --inspect-brk).
2. Open chrome://inspect → your process → Memory → Take heap snapshot.
3. Compare two snapshots after reproducing growth; sort by "Shallow size" / "Retained size". Look for detached DOM nodes (rare in pure Node), ever-growing Maps/Arrays, caches without bounds, and large strings.
4. Clinic.js Heapprofiler / node --heapsnapshot-signal=SIGUSR2 also work on servers without a browser UI.

Docker and small VMs

# Compose / run — give the container enough RAM, then size V8 under it
docker run -m 2g -e NODE_OPTIONS=--max-old-space-size=1536 myimage
# Kubernetes: resources.limits.memory + the same NODE_OPTIONS

If builds only fail in CI: use a larger runner, reduce parallelism, or build artefacts elsewhere and copy them in. See also exit 137 when the cgroup limit wins first.

CRA / Next / webpack tips

• Create React App: "build": "node --max-old-space-size=4096 node_modules/react-scripts/scripts/build.js" as a stopgap; long-term, ejecting or moving to Vite/Next removes a lot of peak memory.
• Next.js: next build is memory-heavy with many routes. Disable unused source maps in production, upgrade Next, or raise the heap for the build step only.
• webpack: upgrade to 5 (persistent caching), turn off devtool: 'eval-source-map' for production, avoid loading giant JSON via require into the bundle.
• Old webpack 4 + Node 17+ often fails with digital envelope routines::unsupported before it gets a chance to OOM — fix that first.

Mystery binary or lockfile blob? What is this?

Related

Killed: exit code 137 (OOM) · Node OpenSSL digital envelope error · EADDRINUSE · ENOSPC no space left · EMFILE too many open files

Questions

Published 5 November 2026.