Memory & Leaks

Source: Node.js API: V8, Node.js API: Command-line API, Node.js API: Process, Node.js API: Performance measurement APIs

A Node.js process uses several kinds of memory, and only one of them is the V8 heap that the flags on this page limit:

Source: Node.js Learn: Understanding and Tuning Memory, Node.js Learn: Tracing garbage collection

The generational split is V8’s answer to the observation that, in a server, nearly everything allocated per request is garbage a moment later. Scavenges are cheap and frequent; the expensive work is reserved for the old generation. When your application retains data it should not, the old generation grows until a major collection cannot reclaim enough and the process aborts with a JavaScript heap out of memory fatal error. The V8 team’s posts on its collector ("Trash talk" and the Orinoco articles, linked in the references) explain the parallel, incremental and concurrent techniques behind this; what matters for Node.js programs is the cost model: collections pause or compete with your JavaScript, so garbage you never create is cheaper than garbage you collect.

Source: Node.js API: v8.getHeapStatistics(), Node.js API: v8.getHeapSpaceStatistics()

The output above is from Node.js 26.10.0 on a 32 GiB macOS machine (abridged; the full list has 13 spaces). Node.js 24.21.0 and 22.23.3 print limits of 4288 and 4144 MiB, and 22 has no shared_space or shared_trusted_space rows: the documentation states that neither the order nor the availability of a space is guaranteed, so never index into the array, look spaces up by space_name. The default limit depends on the machine (about 4 GiB here on a 32 GiB host), so measure it on the machine or container you deploy to rather than quoting a figure.

process.memoryUsage() returns five numbers, in bytes, and the difference between them is the first thing to learn: heapUsed and heapTotal describe the V8 heap, external is memory for C++ objects bound to JavaScript objects, arrayBuffers is the part of external used by ArrayBuffer, SharedArrayBuffer and Buffer, and rss is everything the operating system has resident for the process, including code and native libraries. process.memoryUsage.rss() returns just that one number and is faster.

Source: Node.js API: process.memoryUsage(), Node.js Learn: Understanding and Tuning Memory

Two lessons are visible in the numbers (Node.js 26.10.0, macOS; Node.js 22.23.3 shows the same shape). The 100 MiB Buffer moved external and arrayBuffers but not heapUsed, so a heap limit would not have caught it; and rss did not move either, probably because the operating system had not yet touched the zero-filled pages. Do not read one counter in isolation. constrainedMemory() reports the limit the operating system imposes (for example a Linux control-group limit in a container) and returns 0 when there is none or it is unknown, as on this machine; availableMemory() reports what the process can still obtain. Both are the right inputs for choosing heap flags automatically.

v8.getHeapStatistics() adds the figures that matter for leak hunting: used_heap_size against heap_size_limit (how close you are), external_memory, and two counters the documentation singles out, number_of_native_contexts and number_of_detached_contexts. The documentation describes a detached context as one that was detached and not yet collected, and says a non-zero or rising count indicates a potential leak. v8.getHeapCodeStatistics() reports the size of generated code and metadata.

V8 aborts the process when the old generation cannot grow any further. The flags below move that ceiling, or shape the young generation.

Source: Node.js API: --max-old-space-size, Node.js API: --max-old-space-size-percentage, Node.js API: NODE_OPTIONS

A bigger heap is not a fix for a leak, it only delays the crash and makes each major collection (and each heap snapshot) slower. Raise the limit to match a real working set, and set it below the container’s memory limit with headroom for external memory, the stack and native libraries; Production Deployment and Docker & Containers cover memory sizing in containers. Inside the process you can also cap a single worker thread, which turns a runaway task into an error instead of a crash:

Source: Node.js API: new Worker(), resourceLimits

The same behaviour was observed on Node.js 26, 24 and 22. See Worker Threads for the rest of the worker API, and worker.getHeapStatistics() to watch a worker’s heap from the main thread.

--trace-gc prints one line per collection to standard output. It is the cheapest tool in this page: no extra tooling, low overhead, and enough to tell a leak (live memory that never goes down) from a busy but healthy allocator. The leak below is deliberately blatant, an audit log whose entries are never removed:

Source: Node.js Learn: Tracing garbage collection, Memory leak

Source: Node.js Learn: Tracing garbage collection

Each line breaks down like this (the first scavenge above):

Reading a trace is mostly about two things. First, the after number of the major collections: if used heap after each major collection keeps climbing, the objects are reachable and the collector cannot help, which is a leak or an undersized heap. Second, the gap between collections against the time they take: collections that take longer than the time between them mean the application spends its life in the collector; a gap far larger than the pause is healthy; long gaps and long pauses together suggest the heap is larger than the work needs.

To see what the crash looks like, and which allocation was the last straw, shrink the limit until the process aborts:

Source: Node.js Learn: Tracing garbage collection

Every major collection reclaimed almost nothing (63.1 → 63.1) while current mu sank to 0.001: the signature of a leak. The process exited with code 134 on macOS (observed; the abort signal). The Learn guide’s recipe for finding the allocation context is the same experiment: lower --max-old-space-size until the program hits the limit, read the log, raise it by about 10 percent and repeat; if the pattern persists, it is a leak, and if there is no crash, keep the heap at that size, since a packed heap reduces footprint.

All three lines print Mark-Compact for the major collection (observed on 22.23.3, 24.21.0 and 26.10.0), while the Learn guide’s text and sample output say Mark-sweep, the name of the older algorithm; match on the line shape, not on that word. --trace-gc is a V8 flag and, as noted in the map above, not accepted through NODE_OPTIONS. To trace only a window of the run, switch it from code:

Source: Node.js API: v8.setFlagsFromString()

The documentation warns that changing V8 flags after startup can have unpredictable effects, including crashes, or may simply do nothing; treat this as a debugging aid and list the flags your Node.js version understands with node --v8-options. The same script printed 7, 6 and 13 scavenges on Node.js 26, 24 and 22 (observed), a reminder that the young-generation sizing differs between V8 versions.

For production monitoring, collect the data in-process instead of parsing text. PerformanceObserver with the 'gc' entry type delivers one entry per collection (entry.detail.kind says which kind), and v8.GCProfiler returns the heap statistics before and after every collection between start() and stop():

Source: Node.js API: Garbage Collection ('gc') Details, Node.js API: v8.GCProfiler, Node.js Learn: Tracing garbage collection

The counts differ slightly between lines (Node.js 22.23.3 reported 12 scavenges for the same script). GCProfiler is documented as collecting data for the current thread only.

A heap snapshot is a complete picture of the V8 heap at one instant: every object, its size and what refers to it. Load one into Chrome DevTools (Memory tab) to see which constructors dominate the heap and, through the retainers panel, what keeps an object alive. The format is a JSON document whose schema the documentation calls undocumented and specific to V8, so it can change between V8 versions; use DevTools or another tool matching your Node.js version.

Snapshots are expensive and sensitive. The Learn guide warns that taking one stops all other work on the main thread, can take over a minute on a large heap, and is built in memory, so it can double the heap and, if the machine is short of memory, crash the process; take it from a process that can crash without affecting availability. The API documentation repeats this (about twice the heap size, with a risk of operating-system out-of-memory kills, and a synchronous operation that blocks the event loop). A snapshot also contains the contents of the strings in the heap, which means any token, password or personal data the process holds, so write it with restrictive permissions, keep it out of version control and container images, and never expose an HTTP route that triggers one.

Source: Node.js Learn: Using Heap Snapshot, Node.js API: v8.writeHeapSnapshot(), Node.js API: --heapsnapshot-signal

The leak this section hunts is a typical one: a search endpoint that remembers every distinct query in a Map and never evicts anything.

Source: Node.js Learn: Using Heap Snapshot

A small client sends a range of distinct queries (it takes the port and a start and end number):

Source: Node.js API: fetch()

Following the Learn guide’s two-snapshot method, let the process finish starting up, exercise the suspect feature once so its one-time allocations are out of the way, take a snapshot, keep using the feature, take a second one, and compare:

Source: Node.js API: --heapsnapshot-signal

The default name carries the date, time, process id, thread id (0 for the main thread) and a sequence number, and the files are written to the current working directory. In DevTools, load the older snapshot first and the newer second, select the newer one, switch the view from Summary to Comparison, and look for large positive deltas, then follow the retainers of those objects. Here the delta is one constructor, SearchSession, retained by a Map. To make the same comparison in a script, for instance in a regression test, count the objects of one constructor in each file (a snapshot is a JSON document, which is also why a very large one needs a lot of memory to open):

Source: Node.js Learn: Using Heap Snapshot

The script reads the snapshot layout that V8 emits today (snapshot.meta.node_fields describes the flat nodes array); because the schema is undocumented, treat it as a debugging helper and not a stable parser. The counts match the number of distinct queries sent (200, then 1200), which is how you confirm a suspect before touching the code.

Instead of a signal flag, the application can write a snapshot on demand. Preloading a small module keeps it out of the application code:

Source: Node.js API: v8.writeHeapSnapshot()

Run as node --import ./snapshot-on-signal.mjs leaky-server.mjs and signalled with kill -USR2, it wrote the snapshot on Node.js 26, 24 and 22. Do not combine it with --heapsnapshot-signal on the same signal.

When you need control over where the bytes go, such as a file with restricted permissions, getHeapSnapshot() returns a stream. It still builds the snapshot synchronously, so it does not avoid the pause:

Source: Node.js API: v8.getHeapSnapshot(), Node.js API: stream.pipeline()

The resulting file was 16 MB for about 50,000 small objects (Node.js 26.10.0). exposeInternals and exposeNumericValues (both default false) add V8-internal nodes and numeric values to the snapshot; leave them off unless a tool asks for them. See Streams for pipeline().

A snapshot answers "what is in memory now". The heap profiler answers "who allocated it", by recording allocations over a period. The Learn guide distinguishes two modes:

To use either interactively, start the application with node --inspect index.js (or --inspect-brk for a script that would finish before you attach), connect DevTools, choose the Memory tab, pick "Allocation instrumentation on timeline" or "Allocation sampling", start recording, apply load (the guide uses Apache Benchmark) and stop. Without a browser, Node.js can run the sampling profiler for you:

Source: Chrome DevTools Protocol: HeapProfiler domain

Source: Node.js Learn: Using Heap Profiler, Node.js API: --heap-prof

Here allocate.mjs is a three-line script whose loadCatalog() function pushes 100,000 small objects into an array that outlives the call and whose renderTemplates() produces short-lived strings. The profile points at loadCatalog, the function whose allocations are still live, and not at the garbage that has already been collected (the sampler only keeps objects that are still alive unless told otherwise). Node.js 24.21.0 and 22.23.3 produced the same ranking. A .heapprofile file can also be loaded into the DevTools Memory tab.

Node.js 26.1.0 added a programmatic variant that avoids a whole-process flag and lets you profile just one window:

Source: Node.js API: v8.startHeapProfile()

The options are sampleInterval (bytes, default 524288), stackDepth (default 16), forceGC, and includeObjectsCollectedByMajorGC and includeObjectsCollectedByMinorGC (both default false); the handle supports using and is discarded without a profile if disposed. On Node.js 24 and 22 the import fails with a SyntaxError ("does not provide an export named 'startHeapProfile'", observed), so use --heap-prof there, or worker.startHeapProfile() (v24.9.0 and v22.20.0) to profile a worker from outside. Feeding the profile to top-allocators.mjs ranked the anonymous module-level function, where the loop runs, first (observed).

Almost every Node.js leak is a reachable reference held by something that lives as long as the process. The usual holders:

Source: Node.js Learn: Memory, Node.js API: emitter.addListener()

Watching heapUsed is misleading, since it rises between collections and falls after them. The better signal is the live heap after each major collection, which PerformanceObserver lets you sample, together with the limit:

Source: Node.js API: Class PerformanceObserver

Source: Node.js API: Garbage Collection ('gc') Details, Node.js API: v8.getHeapStatistics()

Performance entries are delivered asynchronously, so the value is read shortly after the collection and is approximate; the trend is what counts (Node.js 24 and 22 climbed the same way). Export the value to your metrics system, alert on a rising floor or on used_heap_size approaching heap_size_limit, and capture a snapshot when it fires. Once a leak is fixed, lock it in with a test. v8.queryObjects() runs a full collection and then counts live objects whose prototype chain includes a constructor, which is exactly what a leak regression test needs, without the cost of serialising a snapshot:

Source: Node.js API: v8.queryObjects()

Source: Node.js API: v8.queryObjects(), Node.js API: Test runner

Both tests passed on Node.js 26, 24 and 22, each printing an ExperimentalWarning for v8.queryObjects(); the documentation says the API is no longer experimental since v25.4.0 and v24.13.1, but the runtime warning was still emitted (observed), so it is cosmetic. The documentation advises against calling the API on constructors you do not control, and only objects created in the current execution context are counted. See Test Runner for the runner.

The overall workflow follows from the pieces above:

Source: Node.js API: V8, Node.js API: Process, Node.js API: Worker threads, Node.js API: Performance measurement APIs

The V8 version also moved with each line (12.4 on Node.js 22, 13.6 on 24, 14.6 on 26), which is why trace lines gained a pooled: field, why the list of heap spaces differs, and why a trace or snapshot from one line may not match another’s tooling exactly.

The two books touch memory only lightly, so they are not a source for this topic. Efficient Node.js (Samer Buna, O’Reilly 2025) mentions that the node command accepts V8 options, including ones that tune the engine’s memory management, tells you to look at DevTools' memory inspector, and in its streams chapter compares the process’s memory with and without streams by watching it grow; it does not describe the heap spaces, garbage collection, snapshots or leak patterns. Node.js Projects (Jonathan Wexler, O’Reilly 2025) names V8 and recommends profiling for excessive memory use as part of mastering the craft, with no tooling. Where you follow either book, apply these points: