Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readNode.js
#Node.js#Memory#Performance#Debugging
3D illustration of a heap of object cubes overflowing a container with a snapshot camera beside it

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:

js
// 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);
bash
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

SignalWhat it meansNext step
heapUsed climbing, external flatJS objects retainedHeap snapshot diff
external/arrayBuffers climbingBuffers or ArrayBuffers retainedFind the reference holding them
rss climbing, heap flatNative memory, buffers, or a child processCheck process.memoryUsage() fields
Grows only under loadPer-request retentionListener or cache keyed by request
Dies at a fixed payload sizeOne allocation too largeStream or raise the limit
ERR_STRING_TOO_LONGA string over ~512 MBNever build one string from a file
FlagEffectUse for
--max-old-space-size=MBSets the old-space ceilingContainers with a known memory limit
--heapsnapshot-near-heap-limit=NWrites N snapshots as the limit nearsProduction diagnosis
--inspectOpens the inspector for DevToolsLocal memory profiling
--max-semi-space-size=MBYoung generation sizeAllocation-heavy services

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. A cache that is not a cache

js
// 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)); });
js
// 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

js
// Broken: a new listener per request, never removed app.use((req, res, next) => { process.on('SIGTERM', () => res.end('bye')); next(); });
js
// 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

js
// 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);
js
// 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

js
// 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 }); });
js
// 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

bash
# Container limit 1 GiB; leave room for native memory and the young generation node --max-old-space-size=768 server.js
yaml
# 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

js
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

MistakeSymptomCorrect fix
--max-old-space-size equals the container limitExit 137, no V8 messageHeap at ~75% of the limit
Map as a cacheSteady growth to the limitLRU with max/ttl
readFile on a large fileOOM at a fixed file sizeStreams
Listener added per requestMaxListenersExceededWarning, slow growthOne listener, or once
setMaxListeners(0) to silence the warningLeak hidden until OOMFix the listener
Heap snapshot taken onceNothing to compareTwo snapshots, diffed
Assuming a leak after one restartActually a traffic spikePlot 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 tools

Small utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Node.js guides

More in Node.js

All Node.js guides

The guides filed next to this one in Node.js, in library order.