skip to content

In Node.js, what do http.Agent's keepAlive and maxSockets options control, and what does http.globalAgent use by default?

level: middleimportance: must knowfreq 60%

answer

  1. pool idle sockets or close them
  2. per-origin cap, then a queue
  3. plain Agent versus the global one
  4. changed in v19

basics

~20 s

keepAlive decides whether an http.Agent pools idle sockets for reuse; maxSockets caps concurrent sockets per origin and queues the rest. new http.Agent() defaults to keepAlive false and maxSockets Infinity; http.globalAgent enables keep-alive with a 5-second timeout.

solid answer

~40 s

An `http.Agent` owns the sockets for `http.request()`. With `keepAlive: true`, a socket whose request finished goes into `agent.freeSockets` for the next request to that origin, up to `maxFreeSockets` (default 256); with the default `false` it is destroyed, and because `maxSockets` is also at its default `Infinity`, the agent sends `Connection: close`. `maxSockets` caps active sockets per origin (the `agent.getName()` key); extra requests wait in the agent's pending queue rather than failing, and `maxTotalSockets` caps all origins together. `http.globalAgent`, used when you pass no `agent`, differs from a plain agent: since v19 it has `keepAlive: true` and a 5-second socket `timeout`, with the usual `'lifo'` scheduling. Since v24.7.0 an agent also closes a pooled socket `agentKeepAliveTimeoutBuffer` (1000 ms) before the server's `Keep-Alive: timeout` hint expires.

go deeper

for a junior

Recall that an http.Agent decides socket reuse, that keepAlive turns pooling on, and that maxSockets is a per-origin limit.

for a middle

Explain the queue behind maxSockets, the free-socket pool behind keepAlive, and how http.globalAgent's v19 defaults differ from a plain new http.Agent().

for a senior

Diagnose reuse races with reusedSocket and ECONNRESET, size maxSockets against an upstream, and spot a custom agent that quietly disabled keep-alive.

for a principal

Decide whether services share one agent per upstream or the global one, and who owns the caps that protect a fragile dependency.

## What an http.Agent is In `node:http`, an **agent** is the object that decides which TCP socket a client request travels on. Every `http.request()` either names one with the `agent` option, uses `http.globalAgent` when the option is absent, or gets a one-off agent with `agent: false`. The agent keys its sockets by **origin**: the string `agent.getName()` builds from host, port and local address (and, for `node:https`, the TLS options that affect reuse). ## keepAlive: pool or destroy - **`keepAlive: false`** (the constructor default): when the agent has no more queued requests for that origin, the socket is destroyed. Because the default `maxSockets` is `Infinity`, this combination also makes the agent send a `Connection: close` header, so the server closes its side too. - **`keepAlive: true`**: the finished socket goes into `agent.freeSockets` and the next request to that origin reuses it, skipping the TCP and TLS handshakes. Pooled sockets get TCP keepalive probes (initial delay `keepAliveMsecs`, default 1000 ms) and are **unref'd**, so idle pooled sockets do not keep the process alive. - **`maxFreeSockets`** (default 256) caps idle sockets kept per origin; extras are closed. - **`scheduling`** picks which idle socket to reuse: `'lifo'` (the default since v15.6.0) takes the most recently used one, which keeps the pool small at low request rates and lowers the risk of picking a socket the server is about to close; `'fifo'` spreads load across more sockets. The option is easy to confuse with two other things. It is not the `Connection: keep-alive` header, and it is not TCP keepalive alone; it is the agent's decision to **reuse** sockets. ## maxSockets: a cap with a queue - **`maxSockets`** (default `Infinity`) is the most sockets the agent opens to **one origin** at once. - When a request arrives and the cap is reached, the request waits in the agent's pending queue (visible as `agent.requests`) until a socket frees up. Nothing fails; latency grows instead. - **`maxTotalSockets`** (default `Infinity`) applies the same idea across all origins. So an agent with `maxSockets: 10` and 50 concurrent calls to one inventory host runs 10 at a time and queues 40. Nothing in the agent limits how long a request waits there, so the cap protects the upstream but needs a per-call deadline beside it, or queued calls can wait indefinitely. ## What http.globalAgent changes | Setting | `new http.Agent()` | `http.globalAgent` | |---|---|---| | `keepAlive` | `false` | `true` | | `timeout` | none | 5000 ms | | `scheduling` | `'lifo'` | `'lifo'` | | `maxSockets` | `Infinity` | `Infinity` | | `maxFreeSockets` | 256 | 256 | The global agent switched to keep-alive with a 5-second timeout in **v19**. A team that copied `new http.Agent()` into a service to "tune" it can therefore silently turn keep-alive **off** compared with the default it replaced. ## Sizing and observing an agent A cap only means something at the scope where it applies: - `maxSockets` is **per agent and per origin**. Two agents pointed at the same host each get the full cap, and every Node process (each cluster worker or replica) has its own agents, so the upstream sees the per-process cap multiplied by the number of processes. - An agent exposes its state as plain objects keyed by origin name: `agent.sockets` (in use), `agent.freeSockets` (idle, keep-alive only) and `agent.requests` (waiting for a socket). Sampling their sizes shows whether calls are queueing behind the cap or the pool is simply busy. - A long `agent.requests` queue with a healthy upstream means the cap is too low for the traffic; a short queue with slow responses means the upstream is the bottleneck and raising the cap would only add load. ## Living with server idle timeouts A pooled socket can be closed by the server at the moment the client reuses it, and the request then fails with `ECONNRESET`. Node gives you three tools: 1. The agent reads the server's `Keep-Alive: timeout=N` hint and expires the socket early by `agentKeepAliveTimeoutBuffer` (default 1000 ms, an option added in v24.7.0). If the hint minus the buffer is zero or less, the socket is not reused at all. 2. `request.reusedSocket` tells you whether a failed request went out on a reused socket, which is what decides whether a safe retry is reasonable. 3. `agent.destroy()` closes every socket when an agent is no longer needed, so a keep-alive pool does not hold connections open until the server times them out. ## Common misreadings - "maxSockets rejects requests over the limit": it queues them. - "The global agent caps hosts at a handful of sockets, like a browser": its default is unlimited. - "Setting keepAlive on http.globalAgent affects fetch()": fetch uses undici's own pool.

  • An agent has maxSockets: 10 and 50 requests to one host start at once. What happens, and what is the risk?
    Ten requests take sockets and forty wait in the agent's pending queue, `agent.requests`, each starting as a socket frees. Nothing errors, so the visible symptom is latency. The agent sets no wait limit on that queue, so pair the cap with a per-call deadline such as `AbortSignal.timeout()` passed as the `signal` option.
  • Why can a keep-alive agent see ECONNRESET on a request that should have worked, and what does Node do about it?
    The server may close an idle pooled socket just as the client reuses it. Node 24's agent expires sockets `agentKeepAliveTimeoutBuffer` (1000 ms by default) before the server's `Keep-Alive: timeout` hint, and `req.reusedSocket` lets code tell this race from a real failure before deciding to retry an idempotent request.

An http.Agent with maxSockets is a bank branch with a fixed number of tellers per queue: when every teller is busy, new customers wait in line rather than being turned away, and with keepAlive on, a teller who finishes stays at the desk for the next customer instead of going home.

  • new http.Agent() keeps connections alive by default.
  • maxSockets makes extra requests fail once the limit is reached.
  • http.globalAgent limits each host to about six sockets, like a browser.
  • The agent's keepAlive option is just the Connection: keep-alive header.
  • Idle pooled sockets keep the Node process from exiting.

Assumes Node 24: http.globalAgent has used keep-alive with a 5-second timeout since v19, scheduling has defaulted to 'lifo' since v15.6.0, and agentKeepAliveTimeoutBuffer arrived in v24.7.0.