Skip to content
Tutorials Center
My learning

Topics

Lesson 85 of 133 ยท Compression, CLI and Tooling

V8, Memory and Garbage Collection

Understand how Node.js uses memory - V8 stack and heap, generational garbage collection, memoryUsage, common leaks, WeakRef and WeakMap, heap limits, snapshots and out-of-memory crashes.

In languages like C you ask for memory and you must give it back. In JavaScript you never do either: you create objects, and at some point the engine notices nobody can reach them any more and reclaims the space. That clean-up is called garbage collection (GC), and it is why a Node.js server can run for months without you writing a single free.

But "automatic" does not mean "free of problems". Servers do run out of memory. Pauses from the collector show up as latency spikes. A cache that only ever grows quietly eats the machine. This lesson explains what V8, the engine inside Node.js, does with your data, how to measure it, how leaks happen, and what tools exist when something goes wrong. It builds on How Node.js Works and leads on to Measuring Performance.

Stack and heap

V8 keeps your program's data in two main places.

The stack is a small, fast, ordered area. Every function call pushes a frame onto it holding the call's local variables and the place to return to. When the function returns, its frame is popped and the space is instantly free. The stack is why deep recursion ends in RangeError: Maximum call stack size exceeded: there is only so much room.

The heap is a large, unordered area where objects live: plain objects, arrays, strings, closures, Maps, class instances. Small values such as numbers and booleans are stored directly where they are used. Anything bigger is allocated on the heap and the variable holds a reference (like an address) to it.

That difference explains a classic puzzle: copying a value versus copying a reference.

Node.js Values are copied, objects are shared

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The stack frame of a function disappears when it returns, but an object on the heap survives as long as something reachable still points at it. That "reachable" idea is the heart of garbage collection.

How V8 collects garbage

V8 does not count references. It uses tracing: starting from a set of roots (global variables, the current stack, active timers and so on) it follows every reference and marks everything it can reach. Whatever is not marked is garbage, and its space is reused. A circular reference between two otherwise unreachable objects is therefore not a problem: neither can be reached, so both go.

Because most objects die young (a temporary array inside a request handler, a string made while parsing), V8 splits the heap into generations:

  • Young generation (also called new space): a small area where new objects are allocated. It is collected often by a fast collector called the scavenger, which copies the survivors to a fresh area. Collecting a mostly-dead area is very cheap, usually a millisecond or less.
  • Old generation (old space): objects that survived a couple of young collections get promoted here. This area is large and is collected less often, by a mark-and-sweep collector that works mostly concurrently and incrementally so your JavaScript pauses only briefly.
  • Large object space holds very big objects directly, and there are separate spaces for compiled code.

You can look at these spaces yourself with node:v8. The numbers change every run, so this example prints only the names of the spaces and the shape of the statistics, never raw sizes.

Node.js The spaces inside the V8 heap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

You do not need to memorize the names. What matters in practice: allocating lots of short-lived garbage is cheap but not free, long-lived data ends up in old space, and a heap that keeps growing in old space is the signature of a leak.

Measuring: process.memoryUsage()

process.memoryUsage() returns five numbers (in bytes):

Field Meaning
rss Resident set size: all memory the process holds in RAM, including code, stack, heap and native memory. This is what the operating system sees.
heapTotal Heap memory V8 has reserved.
heapUsed Heap memory occupied by live and not-yet-collected objects.
external Memory used by C++ objects bound to JavaScript, such as Buffers.
arrayBuffers The part of external used by ArrayBuffers and Buffers.

Notice that Buffers are not on the V8 heap; their bytes live outside it. So a program that reads a 50 MB file into a Buffer shows a big arrayBuffers and rss, but a small heapUsed. This is also why --max-old-space-size does not limit Buffer memory. The next example proves it without printing any machine-specific numbers.

Node.js Buffers live outside the JavaScript heap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Two tips for reading these numbers in real services. First, watch heapUsed after a garbage collection, not at random moments, because it includes garbage not yet collected. Second, graph rss over hours or days: a sawtooth that returns to the same baseline is healthy, a staircase that only rises is a leak.

What a memory leak is in JavaScript

A leak in a garbage-collected language is not forgotten memory; it is memory that is still reachable but no longer needed. The collector cannot know you will never use something, so anything reachable stays. Almost every real leak is one of these:

  1. A cache or registry that only grows: a Map keyed by user id, request id or URL, with nothing that ever removes entries.
  2. Listeners that are never removed: emitter.on(...) called on every request, on a long-lived emitter. See Events and EventEmitter, which also describes the max-listeners warning.
  3. Closures that capture more than you think: a callback kept in a long-lived place also keeps every variable it can see alive.
  4. Timers that never stop: a setInterval holds its callback (and everything the callback references) until you clear it.
  5. Global state: arrays or objects at module level that collect data (logs, metrics, history).

Here is the first kind, with the fix. The unbounded version grows forever when keys keep changing; the bounded one evicts the oldest entry once it reaches its limit. (For a fuller treatment, see Caching in Memory.)

Node.js An unbounded cache versus a bounded one

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Asking the collector: WeakRef, WeakMap and friends

Sometimes you want to attach information to an object without keeping the object alive. JavaScript offers weak references for this.

  • WeakMap and WeakSet: keys must be objects, and holding a key here does not keep it alive. When the key object is collected, its entry disappears. This is perfect for private metadata: wm.set(socket, { lastSeen }).
  • WeakRef: wraps an object; ref.deref() returns the object or undefined if it has been collected. Useful for optional caches.
  • FinalizationRegistry: calls a callback some time after an object has been collected. It is a last-resort cleanup hook. Never depend on it for correctness: the callback may run late or, at process exit, never.

Collection is up to the engine, so normal programs cannot make it happen on demand. To experiment, V8 offers a gc() function, normally hidden behind the --expose-gc flag. We cannot pass flags in the editor, but a script can switch the flag on at runtime and fetch gc from a fresh context. Two subtleties: a WeakRef's target is kept alive until the end of the current JavaScript job, so you must wait a tick before collecting, and the finalizer runs asynchronously.

Node.js Watching an object get collected

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

You will not use gc() in production code. It is a lab tool. The principle is what matters: if nothing strongly references an object, it can be collected, and weak references let you observe that.

Finding a leak with a weak reference

You can build a tiny "was it freed?" test with the same trick. Below, a function attaches a handler to a long-lived emitter, and the handler closes over a large object. After we "clean up" by dropping our own variables, is the object really released?

Node.js A forgotten listener keeps its data alive

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the three results. While the listener is registered, the emitter (a long-lived object) references the listener, which references snapshot, so the object cannot be collected. Calling unsubscribe removes that path, yet the object can still be alive because our own handle variable holds a function that closes over the listener. Only when every path is gone does the weak reference come back empty. The lesson: a strong reference anywhere keeps the object alive, and closures hide references that are easy to miss.

A closure keeps alive every variable it uses, and in some situations V8 also keeps other variables from the same scope. Do not rely on engine details: if a long-lived callback needs only a small value, copy that value into a small variable and let the large object go.

Heap limits and running out of memory

V8 does not let the heap grow without bound. The default limit depends on the Node.js version and the machine's memory (modern versions size it from available RAM), and you can set it with the --max-old-space-size=<megabytes> flag. In our editor the runner uses 256. On your own machine or server you would write (read-only, as the editor cannot take flags):

Terminal
node --max-old-space-size=4096 server.js
# or for every Node process in a container
NODE_OPTIONS="--max-old-space-size=4096" node server.js

Set it a bit below the container or machine memory, leaving room for Buffers, native memory and the operating system. If the heap hits the limit, V8 cannot recover, prints a fatal error and aborts. The process cannot catch this with try/catch: it is a crash of the whole engine, not a JavaScript exception.

To show it safely, the next program starts a child Node process with a tiny 24 MB limit and a loop that allocates forever. The parent survives and reports what happened.

Node.js Running out of heap in a child process (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The child died with the message FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory, killed by the signal SIGABRT. In production, an out-of-memory crash is usually handled by your process manager restarting the service, but the real fix is to find the leak or process data in smaller pieces, for example with streams instead of reading entire files.

Finding leaks in a real service

When a production service's memory climbs, work through these steps:

  1. Confirm the trend. Chart rss and heapUsed over time. Check whether the growth correlates with traffic or with a particular feature.
  2. Check external and arrayBuffers. If these grow but heapUsed does not, the culprit is Buffers, streams that are not consumed, or native add-ons, not ordinary objects.
  3. Take heap snapshots. A heap snapshot is a file listing every object and who references it. You can write one from code with v8.writeHeapSnapshot(), with the --heapsnapshot-signal=SIGUSR2 flag, or from the Chrome DevTools "Memory" tab when connected via node --inspect (see Debugging and Diagnostics). Take one early, run the traffic, take a second one, and open both in DevTools. The comparison view shows which kinds of objects increased, and the retainers panel shows the chain of references keeping an instance alive. Taking a snapshot pauses the process and needs roughly as much extra memory as the heap, so prefer a staging machine or one instance behind the load balancer.
  4. Look for the usual suspects: growing Maps and arrays, listeners, timers, closures, per-request data stored globally.
  5. Fix and verify by repeating the load test and watching the sawtooth return to a flat baseline.

Two flags help at the edges: --heapsnapshot-near-heap-limit=3 writes snapshots just before an out-of-memory crash so you have evidence, and --trace-gc prints a line for every collection (read-only, as we cannot pass flags).

Cheaper copies: structuredClone, transfer and avoiding waste

Memory problems are not only leaks; sometimes they are plain over-use. A few habits help.

  • structuredClone copies deeply, so cloning a large object doubles its memory and takes time proportional to its size. Do not clone in hot paths when a read-only view will do.
  • Transferring moves an ArrayBuffer instead of copying it, which is how postMessage to a worker can be cheap. The original becomes unusable ("detached").
  • Avoid building giant strings and arrays: joining millions of small pieces, JSON.stringify on a huge object and array.map(...).filter(...) chains each create full-size temporary copies. Stream or iterate when the data is large.
  • Release references to large data when you are done with it, especially in long-lived objects: set the field to null or delete the Map entry.
Node.js Copying versus transferring an ArrayBuffer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In JavaScript, what makes an object eligible for garbage collection?

    V8 traces reachability from roots. Unused-but-reachable objects stay, which is exactly how leaks happen; circular references between unreachable objects are collected.
  2. 2. Why does V8 use a young generation and an old generation?

    Short-lived objects are the norm. A fast scavenger over a small area reclaims them cheaply, and only survivors are promoted to the larger, less often collected old space.
  3. 3. A Node.js process shows a large and growing arrayBuffers value but a flat heapUsed. What is the most likely cause?

    Buffers and ArrayBuffers store their bytes outside the V8 heap, so they show up in arrayBuffers and rss, not heapUsed.
  4. 4. What should you rely on a FinalizationRegistry callback for?

    The engine decides when (or whether) to call finalizers. Use explicit close/dispose calls for real resources.
  5. 5. What happens when the V8 heap reaches the --max-old-space-size limit?

    Running out of heap is a fatal engine error that try/catch cannot intercept. Fix the leak, stream the data or raise the limit sensibly.

Summary

  • Primitives and call frames live on the fast stack; objects, arrays, strings and closures live on the V8 heap and are shared by reference.
  • V8 collects by tracing reachability from roots, with a young generation (cheap, frequent) and an old generation (larger, mostly concurrent).
  • process.memoryUsage() reports rss, heapTotal, heapUsed, external and arrayBuffers; Buffers live off the heap.
  • A JavaScript leak is memory that is still reachable but no longer needed: unbounded caches, forgotten listeners, long-lived closures, timers and global state.
  • WeakMap, WeakSet and WeakRef hold objects without keeping them alive; FinalizationRegistry is a best-effort hook, never a cleanup guarantee.
  • --max-old-space-size raises or lowers the heap limit; exceeding it crashes the process and cannot be caught.
  • Use heap snapshots and their comparison view to find retainers, and prefer streams, transfers and bounded structures to reduce memory use.

Next: Debugging and Diagnostics