skip to content

A Node 24 service calls an inventory API with fetch(), checks res.ok and never reads error bodies; sockets climb and calls slow down. Why, and what fixes it?

level: seniorimportance: should knowfreq 45%

answer

  1. the body is part of the request
  2. who frees an unread Response
  3. garbage collection as cleanup
  4. consume, cancel or resume

basics

~20 s

An unread fetch() body can keep its connection busy until the Response is garbage-collected, so new calls open extra sockets or queue behind a cap. Consume every body or call res.body.cancel(); with http.request(), call res.resume().

solid answer

~50 s

In Node's fetch, a connection is free for the next request only once the whole body has been received, and undici receives only as fast as you read: it pushes body bytes into the `Response`'s stream, and once that stream's buffer is full it stops reading the socket. If nobody reads, the only cleanup is a `FinalizationRegistry` that cancels the stream when the `Response` is garbage-collected, which under load is late and unpredictable. Meanwhile the default dispatcher has no per-origin cap, so new calls open more sockets; with a cap, they queue. The fix is to settle every body: read small error bodies with `await res.text()` so the connection can be reused, or `await res.body?.cancel()`, which aborts the request if the body is still arriving and closes that connection. With `http.request()`, a `'response'` handler must read the `IncomingMessage` or call `res.resume()`, or `'end'` never fires and the data stays buffered.

code

javascript · 10 lines
javascript
async function getStock(sku) {
  const res = await fetch(`http://localhost:3000/stock/${sku}`, {
    signal: AbortSignal.timeout(2000),
  });
  if (!res.ok) {
    await res.body?.cancel(); // or: await res.text() to keep the connection
    throw new Error(`inventory answered ${res.status}`);
  }
  return res.json();
}

go deeper

for a junior

Recall that a fetch() Response body must be read or cancelled, and that an http.request() response needs res.resume() if you ignore it.

for a middle

Explain why a response is unfinished until its body is fully received, why an unread body stalls that, and how it blocks connection reuse in both clients.

for a senior

Diagnose climbing sockets from unread bodies, tie the cleanup to garbage collection, and choose between draining and cancelling per call.

for a principal

Decide how a team enforces body discipline, such as one wrapper or a lint rule, rather than relying on reviews.

## The symptom A service calls an inventory API at high volume with `fetch()`. On success it reads `await res.json()`. On failure it checks `res.ok`, logs the status and returns, never touching the body. Over hours, open socket counts climb, upstream connection counts climb, and latency creeps up until a restart clears it. ## Why an unread body holds a connection On HTTP/1.1 a connection carries **one response at a time**, and a response is only finished when its body has been fully received. Node's `fetch()` is implemented by undici, and the chain looks like this: 1. The response headers arrive and the `fetch()` promise resolves with a `Response`. 2. Body bytes are pushed into the `Response`'s `ReadableStream`. When that stream's internal buffer is full, the push reports back-pressure and undici **stops reading the socket**. 3. While part of the body has still not arrived, and nobody consumes, cancels or errors the stream, the request stays in flight, so the connection cannot be returned to the pool for the next request. 4. If your code drops the `Response`, the only cleanup is a **`FinalizationRegistry`** in undici's fetch body code. When the `Response` object is garbage-collected, it cancels the stream with the reason `'Response object has been garbage collected'`. undici's `bodyTimeout` does not rescue it either: that timer does not fire while undici has paused reading for back-pressure. Garbage collection timing depends on heap pressure, not on your request rate, so a busy service can accumulate many stalled connections before any are reclaimed. A small body that arrived completely before you dropped it may already have let the connection go, but its bytes still occupy memory until collection; the larger or slower the body, the worse the leak. ## What it costs, by pool configuration - **Default global dispatcher**: per-origin connections are unlimited (`connections: null`), so each new call simply opens another socket. The cost is file descriptors, TCP and TLS handshakes, and connection slots on the upstream and the load balancer in front of it. - **A capped dispatcher** (for example an undici `Agent` with `connections: 20`): stalled connections count against the cap, so new calls queue. The service looks hung while doing nothing. - **`http.request()`**: the documentation is explicit. If you add a `'response'` handler, the `IncomingMessage` data **must** be consumed, by `read()` on `'readable'`, a `'data'` handler, or `res.resume()`. Until then `'end'` never fires, the socket is not released to the agent, and the buffered data "will consume memory that can eventually lead to a 'process out of memory' error". With no `'response'` handler at all, Node discards the response itself. ## The fixes | Situation | Do this | Effect on the connection | |---|---|---| | You want the body | `await res.json()` / `text()` / `arrayBuffer()` | Read to the end; reusable | | Small error body you don't need | `await res.text()` (or `arrayBuffer()`) | Drained; reusable | | Large or endless body you don't need | `await res.body?.cancel()` | Request aborted; that connection is closed | | `http.request()` response you don't need | `res.resume()` | Drained; socket returns to the agent | Draining keeps the warm connection, which matters when the upstream returns many small 4xx bodies. Cancelling is the right call when the body could be large or never end, because draining it would waste bandwidth and time. ## Confirming the diagnosis 1. Give the suspect upstream its own dispatcher, an undici `Agent` passed in `dispatcher`, so its numbers are separable. Its `stats()` method returns per-origin pool stats: `connected`, `free`, `running`, `pending` and `queued`. 2. A leak shows as `connected` and `running` growing with traffic while `free` stays near zero, even when the upstream answers quickly. 3. For `http.request()`, sample `agent.sockets` and `agent.requests` instead: sockets that never return to `agent.freeSockets` point at responses nobody finished reading. 4. Search the code for every branch that returns or throws after `await fetch()` without reading, draining or cancelling `res.body`. ## Making it hard to get wrong - Wrap outbound calls in one helper that always settles the body on every branch, including the error branch and the early return. - Put the body read under the same deadline as the request: an `AbortSignal.timeout()` passed in `signal` also errors a body that is still streaming. - Watch for the signature: socket counts or upstream connection counts that rise with traffic and fall after a heap collection or restart. - For streaming large bodies to a file or another response, hand `res.body` to the stream utilities so errors and cleanup propagate; that pattern belongs to the streams material. The undici documentation states the rule without exceptions: response bodies must always be fully consumed or destroyed.

  • When would you drain an unwanted body with res.text() rather than cancel it?
    When the body is small and bounded, such as a short JSON error. Draining finishes the response, so the connection goes back to the pool warm and the next call skips the TCP and TLS handshakes. Cancelling aborts the in-flight request and closes that connection, which is better only when the body is large, slow or unbounded.
  • Why might this leak never show up in a load test but appear in production?
    Cleanup depends on garbage collection. A short test with a small heap collects often and reclaims dropped Response objects quickly; a long-running service with a large heap collects rarely, so stalled connections pile up between collections. Error responses are also rare in a happy-path test, so the branch that drops bodies may barely run.

  • If I don't read the body, fetch discards it at once.
  • Garbage collection reclaims unread bodies promptly, so it is harmless.
  • Only error responses need their bodies consumed.
  • Adding a 'response' handler without reading is fine; Node drains it.
  • Cancelling a still-streaming body keeps its connection warm for reuse.

Assumes Node 24 with its bundled undici 7.x: an unread fetch() body is freed only by undici's FinalizationRegistry when the Response is garbage-collected, and the default dispatcher has no per-origin connection cap.