Is it really a Node.js memory leak, or just heap growth?
In a garbage-collected runtime, memory is never "left unfreed." A leak means your code still holds a reference to an object it will never use again, so V8 is not allowed to collect it. A module-level Map that is never pruned, a listener that is never removed, or a closure captured by a long-lived timer can all keep objects reachable. Rising memory alone does not prove that this is happening.
To check, run a non-production replica with --expose-gc and apply constant, representative load. At a fixed interval, call global.gc() and then record process.memoryUsage(). Forcing GC before each reading removes garbage that is collectable but not yet collected, so heapUsed shows only memory that is still reachable. Plot the readings over at least several minutes of steady traffic.
| Pattern after forced GC | Likely cause | Heap snapshot useful? |
|---|---|---|
heapUsed climbs steadily, never flattens |
Retained JS objects (true leak) | Yes |
heapUsed rises, then plateaus |
Caches filling, JIT warm-up, lazy init | No, unless the plateau is too high |
rss or external grows, heapUsed flat |
Buffers, ArrayBuffers, native addons |
Limited. A snapshot shows JS handles, not native allocations |
Profiling is warranted only for the first row, and only once you can reproduce the growth on demand. Taking snapshots before that wastes effort on noise. They are also costly to capture.
// memwatch.js: preload on a NON-production replica under steady load:
// node --expose-gc -r ./memwatch.js server.js
if (typeof global.gc !== 'function') {
throw new Error('Start node with --expose-gc to force GC before sampling');
}
const INTERVAL_MS = 30_000; // one sample every 30s; run for several minutes or more
const MB = 1024 * 1024;
const start = Date.now();
function sample() {
// Collect garbage first so heapUsed reflects only memory that is still reachable
global.gc();
const m = process.memoryUsage();
// One CSV row per sample, written to stderr so it stays out of normal app output
const row = [
Math.round((Date.now() - start) / 1000), // seconds since start
(m.heapUsed / MB).toFixed(1), // live JS objects: steady climb suggests a leak
(m.heapTotal / MB).toFixed(1), // heap V8 has reserved
(m.external / MB).toFixed(1), // C++ memory bound to JS objects (Buffers etc.)
(m.arrayBuffers / MB).toFixed(1), // ArrayBuffer and Buffer backing stores
(m.rss / MB).toFixed(1), // whole process: grows with off-heap and native memory too
];
process.stderr.write(row.join(',') + '\n');
}
process.stderr.write('t_s,heapUsed_mb,heapTotal_mb,external_mb,arrayBuffers_mb,rss_mb\n');
// unref() so the sampler does not keep the process alive on its own
setInterval(sample, INTERVAL_MS).unref();
A preload script that forces GC and then logs process.memoryUsage() as CSV at a fixed interval, so you can plot whether heapUsed climbs steadily, levels off, or stays flat while rss or external grows.
Who should use heap snapshot debugging?
This technique is for engineers who own long-running Node processes: API servers, monoliths, queue workers, WebSocket gateways and similar services that stay up for days or weeks. Short-lived processes such as CLI tools, build scripts and many serverless functions usually exit before a slow leak matters.
It fits best when all of these are true:
- The post-GC baseline from the sampler above climbs steadily in
heapUsed, not only inrssorexternal. - You can reproduce the growth on demand, ideally against a single endpoint or job type.
- You can run a replica, or drain an instance, where a multi-second pause and a temporary memory spike are acceptable.
- You can read the codebase well enough to recognise your own constructors, modules and function names in a retainer chain.
It is also useful for on-call engineers and SREs dealing with recurring OOM kills or restarts. Even if they hand the fix to the owning team, a snapshot diff and a retainer chain give that team a specific reference to remove instead of a vague "memory goes up" report.
It is a poor fit if your growth is off-heap, if you cannot isolate a workload, or if the only environment that shows the problem is a production pod with no memory headroom. The last section covers alternatives for those cases.
How does a heap snapshot work?
A heap snapshot is a serialized copy of the V8 heap's object graph at one moment. When you request one, V8 walks every reachable object and writes it to a .heapsnapshot file, which is JSON. Each object becomes a node with a type, a name (usually its constructor), an ID and a shallow size. Each reference between objects becomes an edge with a type, such as a property, an array element, or a closure's context, plus a name or index.
The graph starts from GC roots: the global object, the stack, handles held by the runtime and native code, and similar entry points. Anything reachable from a root is live. Anything not reachable has already been dropped from the snapshot. That is why a snapshot answers "why is this still here?" rather than "what was allocated?"
When DevTools loads the file, it computes several things from the graph:
- Distance: the length of the shortest path from a GC root to each object.
- Retained size: for each object, the memory that would be freed if it became unreachable. DevTools derives this from the dominator tree. An object dominates another if every path from the roots to the second passes through the first.
- Retainers: the reverse edges, so you can walk from any object back toward a root.
Object IDs stay stable across snapshots taken from the same running process. That is what makes the Comparison view possible. DevTools can tell which objects in snapshot 3 already existed in snapshot 2 and which are new. The workflow in this article relies on that property. You force GC so only reachable objects remain, take snapshots around a repeatable workload, diff them to find objects that accumulate, then follow their retainers to the reference in your code that keeps them alive.
How do you capture a heap snapshot safely from a running Node process?
There are three common ways to capture a snapshot, and they differ mainly in who can trigger them and what they expose.
| Method | How it's triggered | Best fit | Main risk |
|---|---|---|---|
--inspect + Chrome DevTools |
Attach via chrome://inspect, click "Take snapshot" |
Staging, local repro | Open inspector port allows arbitrary code execution |
v8.writeHeapSnapshot() |
Admin-only endpoint or signal handler you write | Production, scripted captures | Endpoint left unauthenticated |
--heapsnapshot-signal |
Send the configured signal to the process | Production, no code changes | Flag not available on older runtimes |
Keep the inspector bound to localhost, which is the default, and reach it through an SSH tunnel. Never expose it on a public interface.
Every method has the same cost. Writing a snapshot is synchronous and blocks the event loop for its full duration. On a large heap that can mean seconds of stalled requests and failed health checks. Generating the snapshot also allocates extra memory, which can approach the size of the heap itself. On a process already near its limit, that allocation can trigger the OOM kill you are trying to diagnose. Before capturing, drain the instance or remove it from load-balancer rotation, or capture from a replica that is serving no traffic. Confirm the container's memory limit leaves enough headroom.
Treat the snapshot file as a credential dump. It contains every live string, including tokens, session data, environment-derived secrets and customer PII. Restrict who can trigger a capture and who can download the file, store it encrypted, and delete it when the investigation ends.
Very large heaps produce snapshot files that DevTools on a typical laptop may fail to load. In that case, reproduce the leak with a smaller heap limit so the snapshot stays manageable.
// heap-snapshot.js: require this once at startup in the service.
// Trigger only after the instance is drained: kill -USR2 <pid>
// Without code changes, `node --heapsnapshot-signal=SIGUSR2 app.js` gives a similar trigger.
// Do not use SIGUSR1. Node reserves it for activating the inspector.
const v8 = require('node:v8');
const fs = require('node:fs');
const path = require('node:path');
// Keep this on a private volume. Snapshots contain secrets, tokens and PII.
const SNAPSHOT_DIR = process.env.SNAPSHOT_DIR || '/var/lib/orders-api/snapshots';
const COOLDOWN_MS = 10 * 60 * 1000; // ignore repeated signals so captures can't pile up
let lastCapture = 0;
process.on('SIGUSR2', () => {
if (Date.now() - lastCapture < COOLDOWN_MS) return;
lastCapture = Date.now();
// Log heap size first. Writing a snapshot can need memory close to this again,
// so compare it with the container limit before you send the signal.
const { used_heap_size, heap_size_limit } = v8.getHeapStatistics();
console.warn(`snapshot requested: heap ${used_heap_size} of ${heap_size_limit} bytes`);
try {
fs.mkdirSync(SNAPSHOT_DIR, { recursive: true, mode: 0o700 });
const file = path.join(SNAPSHOT_DIR, `heap-${process.pid}-${Date.now()}.heapsnapshot`);
// Synchronous: the event loop stalls until the file is fully written.
v8.writeHeapSnapshot(file);
fs.chmodSync(file, 0o600); // only the service user can read it
console.warn(`heap snapshot written: ${file}`);
} catch (err) {
console.error('heap snapshot failed:', err);
}
});
A signal handler that calls v8.writeHeapSnapshot() on SIGUSR2. It logs heap size before capturing, applies a cooldown to repeated signals, and writes the file to an owner-only directory with 0600 permissions, because the snapshot is a sensitive artifact.
How does the three-snapshot technique isolate leaking objects?
Start with a warm-up: send a few hundred requests to the suspect endpoint before taking any snapshot. This fills one-time caches, completes lazy initialization such as module-level singletons, connection pools and compiled templates, and lets the JIT settle. Then take snapshot 1, run the workload N times, take snapshot 2, run it N more times, and take snapshot 3.
In the Comparison view, filter snapshot 3 to objects allocated between snapshots 1 and 2. A one-time allocation made in that window would have been made during warm-up instead, so it does not appear. Short-lived request objects are gone by snapshot 3. What remains was created by the workload and is still reachable afterward. If the count of a constructor grows by roughly N per round (for example, 500 extra closures after 500 requests and another 500 after the next 500), you have a strong leak candidate. Growth that stays flat across rounds is usually caching or noise.
Force garbage collection before each snapshot. Run the process with --expose-gc and call global.gc(), or use the collect-garbage button in DevTools. Also wait for in-flight requests, timers and pending promises to drain. A busy monolith has background jobs and open sockets that hold transient objects, and these can look exactly like leaks if you capture them mid-flight.
The load script should be deliberately boring. It sends identical requests sequentially or at a fixed low concurrency, with a configurable count. Point it at a local or staging instance running production-like settings: the same NODE_ENV, middleware stack, logging and connection pool sizes. The leak should depend only on N, not on random variation in the traffic.
// load.mjs: identical, sequential-ish traffic for the three-snapshot technique (Node 18+, global fetch).
// Usage: TARGET= N=500 node load.mjs
import { createInterface } from 'node:readline/promises';
const TARGET = process.env.TARGET ?? '';
const N = Number(process.env.N ?? 500); // requests per measured round
const WARMUP = Number(process.env.WARMUP ?? 300); // fills caches, finishes lazy init, lets the JIT settle
const CONCURRENCY = Number(process.env.CONCURRENCY ?? 4); // fixed and low: repeatability over throughput
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function run(count) {
let sent = 0, failed = 0;
const worker = async () => {
while (sent < count) {
sent++;
try {
const res = await fetch(TARGET, { headers: { accept: 'application/json' } });
await res.arrayBuffer(); // consume the body so the server completes the request
if (!res.ok) failed++;
} catch { failed++; }
}
};
await Promise.all(Array.from({ length: CONCURRENCY }, worker));
if (failed) console.warn(` ${failed} failed requests: error paths can skew the diff`);
await sleep(2000); // let in-flight timers, promises and sockets drain before snapshotting
}
const rl = createInterface({ input: process.stdin, output: process.stdout });
const snapshot = (n) => rl.question(`Force GC (global.gc() or DevTools), take snapshot ${n}, press Enter... `);
console.log(`warm-up: ${WARMUP} requests`); await run(WARMUP);
await snapshot(1);
console.log(`round 1: ${N} requests`); await run(N);
await snapshot(2);
console.log(`round 2: ${N} requests`); await run(N);
await snapshot(3);
console.log('Compare: filter snapshot 3 to objects allocated between 1 and 2; look for counts growing ~N per round.');
rl.close();
A dependency-free Node load script that warms up the suspect endpoint, then sends two identical rounds of N requests at fixed concurrency and pauses so you can force GC and take each of the three heap snapshots.
How do you read Summary, Comparison and Containment views in Chrome DevTools?
Once the third snapshot is loaded, the Memory panel offers several perspectives on the same heap. Each one answers a different question, so switch between them deliberately rather than staying in the default.
| View | Groups data by | Question it answers | Columns to watch |
|---|---|---|---|
| Summary | Constructor name | What kinds of objects fill the heap right now? | Distance, Shallow Size, Retained Size |
| Comparison | Constructor, diffed against a chosen snapshot | What was created between snapshots and never freed? | # New, # Deleted, # Delta, Size Delta |
| Containment | Object graph from the roots down | What is structurally holding what? | Distance, Retained Size |
In Comparison, select snapshot 3 and compare it against snapshot 2. A constructor whose # Delta matches your N requests, or a multiple of it, is the strongest lead you will get. Containment is less useful for searching. Use it to confirm a structure once you know where to look, such as a module-level object or a cache hanging off global.
The size columns need care. Shallow size is the memory an object occupies by itself: its fields and pointers. Retained size is the memory that would be freed if that object became unreachable, meaning itself plus everything only it keeps alive. A leak usually looks like thousands of small closures, strings or arrays, each with a negligible shallow size. Sorting by shallow size buries the cause under that noise. Sorting by retained size brings up the single Map, array or listener registry that owns them. That object is what your fix has to change.
How do you follow a retainer chain back to a GC root?
Select one leaked instance in the Comparison view and open the Retainers panel below it. Each row is an object holding a reference to the one above it. Expand the first row, then keep expanding the entry with the smallest Distance value, because that is the shortest path to a GC root. A wider tree does not mean a stronger cause. Stop at the first object whose constructor or property name belongs to your codebase.
Many of the rows you pass are V8 and runtime internals. system / Context is the scope object a closure keeps alive. (compiled code) and similar parenthesized entries are engine bookkeeping. Edges labeled context connect a function to the variables it captured. These rows show how the object is held, not why. When a system / Context row appears, look one level up. That is usually the function that captured the variable, and its name tells you which part of your code created the closure. Framework objects, such as an emitter's listener array or a router's middleware stack, are also intermediaries. The reference you can change is usually the call that put something into them.
Names make this readable. An anonymous arrow function appears as (anonymous), and an object literal appears as Object. A named function or class appears under its own name, so a chain like SessionCache → Map → RequestContext points straight to the cause.
This replaces guessing with evidence. Code review shows you every place that could hold a reference. Allocation profiling shows you where objects were created. The retainer chain shows the one reference that is actually keeping the objects alive.
// leak-demo.js: the same leak written two ways, so the Retainers panel differs.
const { EventEmitter } = require('node:events');
const v8 = require('node:v8');
const bus = new EventEmitter();
bus.setMaxListeners(0); // silence the warning so the leak can grow
class RequestContext {
constructor(id) {
this.id = id;
this.payload = Buffer.alloc(64 * 1024); // make each leaked instance easy to spot
}
}
class SessionCache {
constructor() { this.entries = new Map(); }
// Never evicts: this is the first reference our code controls.
remember(ctx) { this.entries.set(ctx.id, ctx); }
}
const sessionCache = new SessionCache();
function handleRequest(id) {
const ctx = new RequestContext(id);
// Anonymous version: retainers show (anonymous) -> system / Context -> ctx
// bus.on('tick', () => ctx.id);
// Named version: retainers show onTickForRequest -> system / Context -> ctx
bus.on('tick', function onTickForRequest() { return ctx.id; });
sessionCache.remember(ctx); // chain: SessionCache -> Map -> RequestContext
}
for (let i = 0; i < 500; i++) handleRequest(`req-${i}`);
// Writes a .heapsnapshot to the current directory; load it in Chrome DevTools > Memory.
// In the snapshot, pick a RequestContext and follow the lowest Distance in Retainers.
console.log('snapshot written:', v8.writeHeapSnapshot());
A small leak shows up in the Retainers panel as a SessionCache → Map → RequestContext chain and as a named listener closure. Naming the class and the function turns Object and (anonymous) rows into references you can trace directly back to the code.
What leak patterns show up most often in Node monoliths?
Most leaks in a long-running monolith come from a handful of shapes. Once you know them, the retainer chain usually tells you which one you have within a few hops.
| Pattern | Typical retainer chain | Fix |
|---|---|---|
Module-level Map or array used as a cache |
(system) → module scope → Map → entry → value |
Bound by size or TTL; evict on write |
| Per-request listener on a long-lived emitter | emitter → _events → listener array → closure → req |
removeListener in teardown, or register with an AbortSignal and abort it |
| Closure captured by an uncleared timer | Timeout → _onTimeout → closure → req/res |
clearTimeout/clearInterval on every exit path |
| Per-tenant or per-key registry | module scope → registry → tenantId → state |
Evict on tenant offboarding or idle expiry |
| Never-settling promise in a pending queue | queue array → resolver closure → Promise → payload |
Time out and reject; drain the queue on shutdown |
Context propagation (AsyncLocalStorage) |
async resource → stored context → request-scoped objects |
Keep the store small; end the long-lived resources that inherit it |
A MaxListenersExceededWarning in your logs almost always means the emitter pattern. The warning fires because listener count keeps rising on one emitter, and a listener count that only goes up is the signature of that leak.
WeakMap and WeakRef fit when the key's lifetime should decide the value's lifetime, such as metadata attached to a socket. Do not reach for them by default. A weak reference makes cleanup depend on garbage collection timing and hides the missing lifecycle. An explicit dispose or unsubscribe call at the point where the owner ends is usually the more honest fix, because it records in code who owns the reference and when it should be released.
How can heap snapshot debugging save engineering time?
Most of the time lost on memory leaks goes to searching, not fixing. Without evidence, teams review every cache, listener and timer that could plausibly hold a reference, add speculative cleanup, deploy, and wait days to see whether the memory graph changed. Each wrong guess costs a full deploy-and-observe cycle. The fix itself is usually a few lines: an eviction policy, a removeListener, a clearTimeout.
The workflow in this article shortens the search in specific ways:
- The post-GC sampler rules out false alarms early. If
heapUsedplateaus or the growth is inexternal, you skip snapshot work entirely and move to the right tool. - The three-snapshot diff narrows the search to one constructor. Instead of auditing the whole codebase, you look at the type whose count grows by about N per round.
- The retainer chain points to one reference. You change the line that holds the object, not every line that might.
- The load script becomes a verification step. Rerun it after the fix. A flat
# Deltaconfirms the leak is gone in minutes on a replica, rather than days in production. - The soak test prevents regressions. Once the reproduction exists, a CI check catches the same class of leak before it ships.
Small habits compound the savings. Named functions and classes make retainer chains readable without extra investigation. A pre-installed signal handler means you can capture evidence during the next incident without a redeploy.
Illustrative estimate, with assumed inputs only: assume a team without snapshots tries three speculative fixes, and each deploy-and-observe cycle takes two days of elapsed time and half a day of an engineer's effort. That is about six days elapsed and one and a half engineer-days, with no guarantee the third guess is right. Assume instead that writing the load script, taking three snapshots and reading the retainer chain takes one engineer-day, and verifying the fix on a replica takes an hour. Under these assumptions the snapshot approach costs a similar amount of effort but removes most of the elapsed time and the uncertainty. The gap widens each time the same leak would otherwise recur. Your own numbers will depend on deploy frequency, how quickly the leak becomes visible, and how familiar the team is with DevTools.
When should you avoid heap snapshots, and what are the alternatives?
A heap snapshot only sees the V8 heap. If rss from process.memoryUsage() climbs while heapUsed stays flat, the growth is elsewhere: Buffer and ArrayBuffer backing stores (watch external and arrayBuffers), memory held by native addons, or allocator fragmentation that the process never returns to the OS. In those cases a clean snapshot does not show that the app is healthy. It shows that you are looking at the wrong memory. Snapshotting also pauses the process and can roughly double memory use while it serializes, which makes it risky on a pod that is already near its limit.
The profiling alternatives answer a different question:
| Tool | Answers | Misses | Overhead |
|---|---|---|---|
| Heap snapshot | Why an object is retained | Off-heap memory | Long pause, memory spike |
| Allocation timeline | Where objects were allocated over time | Retainer chains | High, records every allocation |
| Sampling heap profiler | Statistical allocation hot spots | Retainers, small leaks | Low, but nonzero |
Allocation tracking slows the code paths it measures. That can hide a race-dependent leak, such as listeners that pile up only under specific request timing.
Scheduled restarts and a larger --max-old-space-size are valid stopgaps. Both hide the growth rate, though, so track the post-GC baseline before and after you apply them.
The durable fix takes upfront effort. You need a reproducible load script and a soak test that forces GC with --expose-gc and asserts that post-GC heap growth stays below a threshold across thousands of iterations. That costs days of work once, compared with paying for the same incident again every few weeks.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to node.js memory leak heap snapshot, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.