Node.js JavaScript heap out of memory: Snapshots and Real Leaks
Distinguish needs more from leaks before raising the flag: external memory and heap tell different stories, and a heap ceiling at three quarters of the container limit keeps V8 able to report.

Introduction & Quick Summary
Symptom. The process dies with FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory followed by a Mark-Compact trace and a long […] address dump. In containers it shows as exit code 134 or 137 with no application log at all; under a supervisor it restarts and repeats hours or days later, always after a period of growth. In some runs the message is FATAL ERROR: invalid array length or ERR_STRING_TOO_LONG instead.
Cause. The V8 old space filled up and the GC could not free enough before the allocation that failed. Either the process genuinely needs more live memory than the limit (a large buffer, a giant JSON payload, a big in-memory cache), or it leaks: a module-level Map that only grows, a listener attached per request, a closure retained by a timer, a promise chain that keeps a request object alive. Node sizes the limit from available memory with a comfortable ceiling on 64-bit builds; a container with a lower memory limit will be OOM-killed before V8 ever raises its own error.
Fix. Distinguish "needs more" from "leaks": take a heap snapshot at two points and compare retained sizes, check external memory for buffers, then either bound the data structure or stream it. Raise --max-old-space-size only after the limit is understood and always below the container limit.
Core Mechanics, Signatures & Reproducible Setup
V8 splits memory into a young generation and an old space (plus large-object space). Objects that survive two scavenges are promoted to old space; a major GC compacts it. process.memoryUsage() reports heapUsed, heapTotal, external (Buffers, ArrayBuffers), arrayBuffers, and rss. The fatal error is about the heap limit, so a Buffer-heavy process can be killed by the cgroup while its heap looks small.
Reproduce a leak with a diagnostic entrypoint:
// leak.js — grows ~10 MB/s until the heap limit
const cache = new Map();
let i = 0;
setInterval(() => {
cache.set(`key-${i}`, Buffer.alloc(1024 * 1024).toString('base64'));
i += 1;
if (i % 50 === 0) {
const m = process.memoryUsage();
console.log(i, {
heapUsedMB: Math.round(m.heapUsed / 1e6),
rssMB: Math.round(m.rss / 1e6),
externalMB: Math.round(m.external / 1e6),
});
}
}, 10);node --max-old-space-size=128 leak.js # fails in seconds, deterministic
node --heapsnapshot-near-heap-limit=2 leak.js # writes .heapsnapshot files--heapsnapshot-near-heap-limit=2 writes two snapshots as the limit approaches, which is the cheapest way to get evidence from a production incident without reproducing it. Open the .heapsnapshot in Chrome DevTools → Memory → Load, then compare the two snapshots by "Objects allocated between snapshot 1 and 2".
Key Comparison Table
| Signal | What it means | Next step |
|---|---|---|
heapUsed climbing, external flat | JS objects retained | Heap snapshot diff |
external/arrayBuffers climbing | Buffers or ArrayBuffers retained | Find the reference holding them |
rss climbing, heap flat | Native memory, buffers, or a child process | Check process.memoryUsage() fields |
| Grows only under load | Per-request retention | Listener or cache keyed by request |
| Dies at a fixed payload size | One allocation too large | Stream or raise the limit |
ERR_STRING_TOO_LONG | A string over ~512 MB | Never build one string from a file |
| Flag | Effect | Use for |
|---|---|---|
--max-old-space-size=MB | Sets the old-space ceiling | Containers with a known memory limit |
--heapsnapshot-near-heap-limit=N | Writes N snapshots as the limit nears | Production diagnosis |
--inspect | Opens the inspector for DevTools | Local memory profiling |
--max-semi-space-size=MB | Young generation size | Allocation-heavy services |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. A cache that is not a cache
// Broken: unbounded, no eviction
const cache = new Map();
app.get('/user/:id', async (req, res) => {
if (!cache.has(req.params.id)) cache.set(req.params.id, await loadUser(req.params.id));
res.json(cache.get(req.params.id));
});// Fixed: bounded LRU with a size cap and a TTL
import { LRUCache } from 'lru-cache';
const cache = new LRUCache({ max: 5000, ttl: 1000 * 60 * 10 });
app.get('/user/:id', async (req, res) => {
let user = cache.get(req.params.id);
if (!user) {
user = await loadUser(req.params.id);
cache.set(req.params.id, user);
}
res.json(user);
});An unbounded Map keyed by user input is the most common Node heap leak in production. The heap snapshot shows it immediately: thousands of objects retained by a single Map entry point.
2. Listeners per request
// Broken: a new listener per request, never removed
app.use((req, res, next) => {
process.on('SIGTERM', () => res.end('bye'));
next();
});// Fixed: one listener at startup
const sockets = new Set();
server.on('connection', (s) => { sockets.add(s); s.on('close', () => sockets.delete(s)); });
process.on('SIGTERM', () => { for (const s of sockets) s.destroy(); process.exit(0); });MaxListenersExceededWarning is the early symptom; without it, each request retains its response object through a closure until the process dies. As a guard, process.setMaxListeners(0) silences the warning and hides the leak — do not.
3. Buffers are external, not heap
// Broken: reads a 900 MB file into memory three times
const a = await fs.promises.readFile('dump.json');
const b = JSON.parse(a);
const c = JSON.stringify(b);// Fixed: parse incrementally
import { createReadStream } from 'node:fs';
import { chain } from 'stream-chain';
import { parser } from 'stream-json';
import { streamArray } from 'stream-json/streamers/StreamArray';
const pipeline = chain([createReadStream('dump.json'), parser(), streamArray()]);
for await (const { value } of pipeline) await handle(value);JSON.parse on a large document allocates the string, the UTF-16 string, the parsed objects and arrays, and the intermediate structure — several times the file size at peak. A streaming parser keeps the working set at a few chunks. Buffers themselves show under external/arrayBuffers, so if heapUsed is stable while the process still grows, look there rather than at object retention.
4. Timers and closures retaining requests
// Broken: the setInterval closure keeps `req` alive forever
app.post('/job', (req, res) => {
const id = req.body.id;
setInterval(async () => { await ping(id, req.headers.authorization); }, 1000);
res.json({ ok: true });
});// Fixed: store only primitives, clear the timer, unref if it must outlive the request
const token = String(req.headers.authorization); // copy, then drop `req`
const timer = setInterval(() => ping(id, token), 1000);
timer.unref();
req.on('close', () => clearInterval(timer));Capturing req/res in a callback that outlives the request retains the socket, the headers, and the body buffer. Extracting the primitive values you need is a one-line habit that removes a whole class of leak.
5. Raising the limit without lying to the kernel
# Container limit 1 GiB; leave room for native memory and the young generation
node --max-old-space-size=768 server.js# Kubernetes: keep the limit above the heap ceiling
resources:
requests: { memory: "768Mi" }
limits: { memory: "1Gi" }If --max-old-space-size equals the container limit, V8 reaches its ceiling at the same moment the cgroup does, and the kernel kills the process before V8 can print the heap error — which is why some incidents show only exit 137. A heap ceiling at roughly 70–75% of the container limit leaves room for buffers, native allocations, and the young generation.
6. Measuring before changing
import v8 from 'node:v8';
import { monitorEventLoopDelay } from 'node:perf_hooks';
v8.setFlagsFromString('--expose-gc');
const h = monitorEventLoopDelay({ resolution: 20 });
h.enable();
setInterval(() => {
const m = process.memoryUsage();
console.log(JSON.stringify({
heap: Math.round(m.heapUsed / 1e6),
rss: Math.round(m.rss / 1e6),
external: Math.round(m.external / 1e6),
p99LoopMs: (h.percentile(99) / 1e6).toFixed(1),
}));
}, 15_000);An event-loop p99 that rises as heap grows is the signature of GC pressure rather than a slow handler. Logging the three memory fields turns "it restarts every two days" into a slope you can attribute to a specific deploy.
Common Compilation/Runtime Mistakes & Version Gotchas
| Mistake | Symptom | Correct fix |
|---|---|---|
--max-old-space-size equals the container limit | Exit 137, no V8 message | Heap at ~75% of the limit |
Map as a cache | Steady growth to the limit | LRU with max/ttl |
readFile on a large file | OOM at a fixed file size | Streams |
| Listener added per request | MaxListenersExceededWarning, slow growth | One listener, or once |
setMaxListeners(0) to silence the warning | Leak hidden until OOM | Fix the listener |
| Heap snapshot taken once | Nothing to compare | Two snapshots, diffed |
| Assuming a leak after one restart | Actually a traffic spike | Plot memory against request rate |
Version notes: V8 sizes the default old space from the machine's memory, so a Node upgrade on a larger runner gives the same code a different ceiling — set --max-old-space-size explicitly when the limit matters. Read arrayBuffers as well as external when a Buffer-heavy service is involved; comparing a single field across majors is misleading. --heapsnapshot-near-heap-limit writes to the working directory, which is often read-only in a container — point the cwd at a writable volume or the snapshot is silently not written.
For the surrounding work, the JSON formatter reads a --heapsnapshot metadata dump or a large log line that a structured logger emitted, the text diff tool compares two memory reports taken an hour apart, and the base64 tool is a quick way to inspect what a sampled field actually contains when the retained size points at a string you cannot identify.
Try matching browser tools
All toolsSmall utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Node.js guides
All Node.js guidesNode.js EventEmitter: once, error Events, and Listener Memory Leaks
emit is synchronous, so a throwing listener aborts the rest. An error event with no listener crashes the process, and a listener per request is the classic leak.
Node.js fs/promises: Read, Write, Watch, and Atomic File Operations
writeFile truncates before writing, so a crash leaves half a file. The atomic pattern is temp file, fsync, rename; readFile loads everything, so large files need streams.
Node.js Streams: Readable, Writable, Transform, and pipeline
pipe() forwards data but not errors; pipeline() destroys the chain and rejects. Backpressure is the false return from write(), and _flush that never calls back hangs forever.
Node.js crypto: Hashing, HMAC, AES-GCM, and Random Bytes
Hashing, HMAC, AES-256-GCM and randomness solve different problems. Never reuse a GCM nonce, never hash a password with sha256, and compare secrets with timingSafeEqual.
More in Node.js
All Node.js guidesThe guides filed next to this one in Node.js, in library order.