Node.js Error: heap_out_of_memory — Heap Out of Memory

<--- Last few GCs --->
[12345:0x130008000]   65432 ms: Mark-sweep 4083.5 (4127.4) -> 4079.2 (4127.4) MB, 2087.4 / 0.0 ms  (+ 0.0 ms in 0 steps since start of marking, biggest step 0.0 ms, walltime since start of marking 2088 ms) (average mu = 0.106, current mu = 0.020) allocation failure; scavenge might not succeed
<--- JS stacktrace --->
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
 1: 0x100b95c4c node::Abort() [/usr/local/bin/node]
 2: 0x100b95dd8 node::OnFatalError(char const*, char const*) [/usr/local/bin/node]

JavaScript heap out of memory is V8 throwing in the towel. Garbage collection ran over and over, couldn’t free enough space, and the engine aborts rather than leave you in a half-corrupted state. The error always means one of two things: either your real working set is bigger than the configured heap, or you have a leak.

The default reflex — bump --max-old-space-size — only helps the first case. For the second, it just delays the crash. The reliable path is a heap snapshot: see what’s retained, fix the retention, watch the sawtooth come back.

Why this happens

• Large data loaded fully into memory. Reading a 2GB JSON file with `JSON.parse(fs.readFileSync(...))`, loading every row of a query into a single array, or buffering an entire HTTP response body. Stream the data instead — Node's stream APIs were built for exactly this.
• Event listener leak. Adding listeners to an `EventEmitter` (or DOM-style emitter) without ever removing them. Node logs `MaxListenersExceededWarning: 11 listeners added` first; if you ignore the warning, you eventually run out of heap. Common around `process.on('uncaughtException')` in test suites.
• Cache without bounds. An in-memory cache (`Map`, `WeakMap`, plain object) that grows unbounded over the process lifetime. Production: a `Map` keyed by user ID with no eviction, holding response data, growing forever. Replace with `lru-cache`.
• Closure holding more than it needs. A function returned from another function captures the entire parent scope. If the parent had a 200MB buffer, the closure keeps it alive. Visible in heap snapshots as 'closure → context → buffer'.
• Worker spawn / require explosion. Forking workers in a tight loop, or `require()`ing modules dynamically without limit. Each worker has its own heap; spawning 1000 workers exhausts memory at the OS level too. Monorepos that import every workspace at startup also hit this.

How to fix it

Fixes are ordered by likelihood. Start with the first one that matches your context.

# Run with inspector + auto-snapshot on near-heap-limit:
node --inspect \
     --heapsnapshot-near-heap-limit=3 \
     --max-old-space-size=4096 \
     server.js

# Or programmatic snapshot (good for long-running services):
# require('v8').writeHeapSnapshot('/tmp/heap.heapsnapshot');
# then load in Chrome DevTools → Memory tab.

import { createReadStream, createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import { parse } from 'csv-parse';
import { stringify } from 'csv-stringify';

// Process a 5GB CSV row-by-row with O(1) memory.
await pipeline(
  createReadStream('huge.csv'),
  parse({ columns: true }),
  async function* (rows) {
    for await (const row of rows) {
      yield { ...row, processed: true };
    }
  },
  stringify({ header: true }),
  createWriteStream('out.csv'),
);

import { LRUCache } from 'lru-cache';

export const userCache = new LRUCache<string, User>({
  max: 10_000,                       // count
  maxSize: 50 * 1024 * 1024,         // 50MB
  sizeCalculation: (v) => JSON.stringify(v).length,
  ttl: 5 * 60 * 1000,                // 5min
  updateAgeOnGet: true,
});

Detection and monitoring in production

Track Node's `process.memoryUsage().heapUsed` and `heapTotal` as gauges in your APM. Healthy services have a sawtooth pattern (GC reclaims regularly); leaking services trend upward without dropping back. Alert on heapUsed > 80% of max_old_space_size for over 5 minutes. Use `--heapsnapshot-near-heap-limit=N` in production to capture N snapshots automatically before the crash — invaluable for post-mortems.