ERROR node memory ai_generated true

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

ID: node/heap-out-of-memory

Also available as: JSON · Markdown
78%Fix Rate
85%Confidence
45Evidence
2016-03-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
20 active — — —
18 active — — —

Root Cause

Heap out of memory in Node 20 on Linux is commonly caused by large dataset processing, memory leaks in long-running processes, or aggressive bundler configurations. Increasing the heap limit is a valid short-term fix, but long-term resolution requires identifying the memory consumer.

generic

Workarounds

  1. 82% success Increase heap size via NODE_OPTIONS environment variable 
    export NODE_OPTIONS='--max-old-space-size=4096' && node app.js. For build tools: NODE_OPTIONS='--max-old-space-size=4096' npm run build. Adjust the value (in MB) based on available system memory. Common values: 4096 (4GB), 8192 (8GB).

    Sources: https://nodejs.org/api/cli.html#node_optionsoptions

  2. 70% success Profile and fix memory leaks using heap snapshots 
    Run with --inspect flag: 'node --inspect app.js'. Open chrome://inspect in Chrome, take heap snapshots before and after the operation, compare retained objects. Look for growing arrays, event listener accumulation, or unclosed streams.

    Sources: https://nodejs.org/en/docs/guides/diagnostics/memory/using-heap-snapshot

  3. 75% success Process data in streams or chunks instead of loading everything into memory 
    Replace fs.readFileSync or full-buffer approaches with Node.js streams (fs.createReadStream, Transform streams). For JSON, use streaming parsers like 'stream-json' or 'JSONStream' instead of JSON.parse on the full file.

    Sources: https://nodejs.org/api/stream.html#stream

Dead Ends

Common approaches that don't work:

  1. Blindly setting --max-old-space-size to very large values (e.g., 32768) without investigating the root cause 60% fail

    Raising the heap limit without understanding why memory is exhausted merely delays the crash. If there is a memory leak, the process will eventually exhaust even the larger limit, and on constrained environments (containers, CI) this causes OOM kills. This masks the real problem.

  2. Upgrading Node.js version alone 85% fail

    While newer Node versions may have slightly different default heap limits and improved GC, upgrading does not fix application-level memory leaks or fundamentally undersized heaps for legitimate workloads.

Error Chain

Frequently confused with: