Finding the Retaining Path

The Detective Work of Memory Debugging

You have taken a heap snapshot. You have found the leaked objects. You know what is leaking. But that is only half the story. The real question is: why is the garbage collector not collecting it?

Every object in memory is alive for one reason: something reachable from a GC root holds a reference to it. The retaining path is the chain of references from the GC root down to your leaked object. Find the path, and you find the bug.

GC Roots: Where It All Starts

In V8, an object can only survive garbage collection if it is reachable from a GC root. These are the starting points the garbage collector considers "definitely alive":

If there is no path from any GC root to an object, V8 collects it. If there is even one path, no matter how convoluted, the object stays alive.

Reading Retaining Paths in DevTools

When you click on an object in a heap snapshot, the lower pane shows its Retainers — the objects that hold references to it. This is your retaining path, read from bottom to top.

A typical retaining path looks like this:

your_leaked_object
  ↑ in property "data" of Object @123456
    ↑ in property "cache" of Module @789012
      ↑ in variable "moduleCache" of Window @1
        ↑ GC Root: Window

Read this from bottom to top:

1. The Window object (a GC root) has a variable moduleCache
2. moduleCache is a Module object with a cache property
3. cache is an Object with a data property
4. data is your leaked object

The fix: somewhere in this chain, there is a reference that should have been cleared. Maybe moduleCache should have been cleaned up. Maybe cache.data should have been set to null after use.

Step-by-Step Debugging Workflow

Here is the process I use every time I need to find a retaining path:

Handling Multiple Retaining Paths

Sometimes an object has multiple retaining paths — it is kept alive by more than one root. DevTools shows all of them. You need to fix every path to make the object collectible.

const moduleCache = new Map();
const debugLog = [];

function loadWidget(id) {
  const widget = createWidget(id);

  moduleCache.set(id, widget);
  debugLog.push({ widget, loadedAt: Date.now() });

  return widget;
}

function unloadWidget(id) {
  const widget = moduleCache.get(id);
  widget.destroy();
  moduleCache.delete(id);
  // BUG: widget is still in debugLog!
}

After unloadWidget, the widget has one retaining path removed (moduleCache) but still has another (debugLog). Both must be cleaned up.

Common Retaining Path Patterns

Pattern 1: Module-Level Cache

leaked_object
  ↑ in value of Map entry
    ↑ in property "[[Entries]]" of Map @12345
      ↑ in variable "cache" of (closure) @67890
        ↑ in context of module scope
          ↑ GC Root: system / Context

The fix: implement cache eviction (LRU, TTL, or WeakMap if keys are objects).

Pattern 2: Forgotten Event Listener

leaked_component_data
  ↑ in variable "props" of (closure) @11111
    ↑ in property "handler" of EventListener
      ↑ in property "listeners" of Window @1
        ↑ GC Root: Window

The fix: remove the event listener in the cleanup function.

Pattern 3: Detached DOM via React Ref

Detached HTMLDivElement
  ↑ in property "current" of Object @22222
    ↑ in property "ref" of FiberNode @33333
      ↑ in property "stateNode" of FiberNode @44444
        ↑ ... (React internal fiber tree)
          ↑ GC Root: system / Context

The fix: ensure refs are cleaned up when components unmount. If you copy ref.current into an external variable, null it in a cleanup effect.

Pattern 4: Promise Chain Retention

large_response_data
  ↑ in variable "data" of (closure) @55555
    ↑ in property "handler" of PromiseReaction
      ↑ in property "reactions" of Promise @66666
        ↑ in variable "pendingRequest" of (closure)
          ↑ GC Root: system / Context

The fix: ensure promises resolve or reject (not left pending), and avoid storing large data in long-lived promise chains.

Advanced: Distance from GC Root

In the Summary view, the Distance column shows the shortest number of reference hops from any GC root to the object. This is useful for triage:

• Distance 1-3: directly reachable from global state. Look for module-level variables or properties on window.
• Distance 4-10: typical for objects nested in application data structures.
• Distance 10+: deeply nested. Often means the object is retained through a long chain (like a linked list or deep component tree).

Objects with unexpectedly high distance values might be retained through convoluted chains that are hard to spot. Sort by distance to find these outliers.