Debugging a Memory Leak in Node.js With Heap Snapshots
A single heap snapshot mostly tells you what's in memory right now — comparing two of them is what actually turns a vague leak into a specific line of code.
A side project of mine — a small Node.js server handling webhook events — crept up in memory usage every few days until it crashed, and restarting it "fixed" the symptom without ever telling me why. Comparing two heap snapshots taken a few hours apart was what finally pointed at the actual cause: an array I was appending event history to and never trimming.
A heap snapshot is a full capture of every object currently allocated in a running Node process's memory at one instant, along with what's still holding a reference to each of them — available through Chrome DevTools when Node is launched with --inspect, or programmatically through the built-in v8 module. On its own, a single snapshot mostly tells you what's in memory right now, which is useful but not yet a leak diagnosis.
The real technique is comparative: take a snapshot, let the suspected leaking behavior run for a while, take a second snapshot, and use DevTools' "Comparison" view between the two. Objects that grew in count between the two snapshots — especially by an amount roughly proportional to how many times the leaking code path ran — are the strongest leak candidates, since normal, healthy memory use should mostly stabilize rather than climb every time the same operation runs.
Once a growing object type is identified, DevTools lets you inspect its retainers — the chain of references keeping each instance alive instead of being garbage collected. That retainer chain is usually where the actual bug reveals itself: an array or Map that keeps getting appended to without anything ever removing old entries, a closure capturing more than it needs and outliving its useful purpose, or an event listener registered repeatedly without ever being removed.
In my case, the retainer chain led straight to an in-memory event-history array with no size cap, growing by one entry per webhook received and never trimmed — an easy mistake that looks completely reasonable in isolation and only shows up as a problem after the process has run long enough to accumulate a real backlog. Comparative heap snapshots are the tool that turns "memory usage keeps climbing" from a vague symptom into a specific line of code.