How do undici, fetch and Axios relate in Node.js?
Node.js ships three overlapping ways to make an HTTP request. They share less code than their APIs suggest.
undici is an HTTP/1.1 client developed under the Node.js project. It does not use the core http module. It manages its own sockets through Client, Pool and Agent objects, and it exposes a lower-level request API alongside a fetch implementation.
Global fetch in Node is undici's fetch, bundled into the runtime. When you call fetch() without extra options, requests go through a process-wide global dispatcher, which is an undici Agent with default pool settings. The bundled copy is pinned to whatever undici release your Node version shipped with. That release can differ from the undici package you install from npm. Behaviour, defaults and option names may therefore not match between the two. Mixing objects across that boundary, such as passing an npm-installed dispatcher to the built-in fetch, can fail in confusing ways.
Axios in Node uses an adapter built on the core http and https modules by default. Its connection reuse comes entirely from the http.Agent or https.Agent you hand it, including whether keep-alive is enabled and how many sockets it may open. Axios adds interceptors, transforms and error conventions, but it does not pool connections itself.
The practical consequence is the thesis of this article. Latency and failure behaviour for internal calls are decided mostly by the pool, keep-alive and timeout settings underneath the client. Swapping client libraries without changing those settings rarely fixes a slow or stalling service.
Application code
|
+-------------------+-----------------------+
| | |
v v v
+-----------+ +---------------+ +-------------------+
| global | | npm undici | | Axios |
| fetch() | | request/fetch | | interceptors, |
| (bundled | | (installed | | transforms |
| undici) | | version) | | Node http adapter |
+-----+-----+ +-------+-------+ +---------+---------+
| | |
v v v
+-----------+ +---------------+ +-------------------+
| global | | undici Agent /| | http.Agent or |
| dispatcher| | Pool / Client | | https.Agent |
| (Agent, | | options you | | keepAlive, |
| defaults) | | choose | | maxSockets |
+-----+-----+ +-------+-------+ +---------+---------+
| | |
+---------+---------+ |
| undici-managed sockets | core http/https
v v
+-----------------------------------------------------------+
| TCP/TLS sockets to internal services |
| pool size, keep-alive and timeouts here decide latency |
+-----------------------------------------------------------+
Note: bundled undici (fetch) and npm undici may be different versions;
do not pass an npm-installed dispatcher to the built-in fetch.
Global fetch and npm undici manage their own sockets via undici dispatchers, while Axios relies on core http/https Agents; in every path, pool, keep-alive and timeout settings shape behaviour.
How does it work? The path of a single request
All three clients follow the same basic lifecycle once you look below the API. The differences lie in which object owns each step.
- Pick a pool. The request is routed by origin (scheme, host and port). An undici
Agentkeeps a separatePoolper origin. APoolis a set ofClientobjects, and eachClientwraps one connection. A corehttp.Agent, which Axios uses, keeps its own per-origin lists of free sockets and pending requests. - Get a socket. If an idle keep-alive socket is available, the request uses it and skips the handshake. If none is idle and the pool is below its limit (
connectionsin undici,maxSocketsin a core agent), a new TCP connection is opened, plus a TLS handshake for HTTPS. If the pool is full, the request waits in a queue. That queue time shows up to your code as latency, even though no bytes have been sent. - Send and wait for headers. The request is written to the socket. The client parses the status line and headers when they arrive.
fetchresolves itsResponseat this point. undici'srequest()resolves withstatusCode,headersand abodystream. - Consume the body. The socket still belongs to this request until the body has been fully read or discarded. Axios reads the whole body for you before resolving. With
fetchandrequest(), your code is responsible for it. - Return or close the socket. With keep-alive, the socket goes back to the pool and sits idle until another request uses it or an idle timeout closes it. Without keep-alive, it is closed, and the next request pays for a new handshake.
Every tuning knob in the rest of this article maps onto one of these steps. Pool size governs step 2. Connect, headers and body timeouts govern steps 2 to 4. Body handling governs step 4. Keep-alive idle timeouts govern step 5.
Why do keep-alive and connection pooling dominate service-to-service latency?
A new connection costs at least one network round trip for the TCP handshake before any request bytes move. TLS 1.3 adds another round trip plus key-exchange CPU on both ends, and TLS 1.2 adds more. Keep-alive leaves the socket open after a response so the next request can use it. A connection pool manages a set of these open sockets per origin. For large transfers the handshake is a small fraction of the total. For internal calls with small JSON payloads and fast handlers, it can be the largest single cost.
Illustrative estimate
This is an illustrative estimate, not a measurement. Assumed inputs: 0.5 ms round-trip time within a zone, 2 ms server processing, TLS 1.3, and 1 ms of combined handshake CPU. Your own figures will differ.
- Reused connection (illustrative, from the assumed inputs): 0.5 ms round trip + 2 ms server time = 2.5 ms.
- New connection (illustrative, from the assumed inputs): TCP (0.5 ms) + TLS (0.5 ms + 1 ms) adds 2 ms, for a total of 4.5 ms. Under these assumptions, that is 80% slower than a reused connection.
- Reused across 100 requests (illustrative): the assumed 2 ms handshake cost works out to 0.02 ms per request.
Verifying reuse
Count connections rather than assuming them. Run the client at a steady request rate and watch the number of new sockets over time. On Linux, ss shows established and TIME_WAIT connections to the upstream. If TIME_WAIT keeps growing, sockets are being closed and reopened instead of reused. On the server or proxy side, compare the TLS handshake count with the request count. When connections are reused, there should be far fewer handshakes than requests.
The trade-off
Connection-level (L4) load balancers choose a backend once per connection. A client with a large pool of long-lived connections keeps sending traffic to whichever backends it reached first, and instances added during scale-out receive little of that client's load. To spread traffic again, cap connection lifetime or the number of requests per connection, or balance at L7.
// Count new TCP sockets vs requests to check whether connections are reused.
// Run against an internal HTTP endpoint (placeholder host below).
const http = require('node:http');
const TARGET = { host: 'orders.internal.example', port: 8080, path: '/healthz' };
const REQUESTS = 100;
async function run(label, agent) {
const seen = new WeakSet(); // each socket object counted once
let newSockets = 0;
for (let i = 0; i < REQUESTS; i++) {
await new Promise((resolve, reject) => {
const req = http.get({ ...TARGET, agent }, (res) => {
res.resume(); // drain the body so the socket can return to the pool
res.on('end', resolve);
});
req.on('socket', (socket) => {
if (!seen.has(socket)) { seen.add(socket); newSockets++; }
});
req.on('error', reject);
});
}
console.log(`${label}: ${REQUESTS} requests, ${newSockets} new sockets`);
agent.destroy(); // close pooled sockets so the process can exit
}
(async () => {
// No keep-alive: expect roughly one new socket (and handshake) per request.
await run('keepAlive=false', new http.Agent({ keepAlive: false }));
// Keep-alive pool: sequential requests should reuse a single socket.
await run('keepAlive=true ', new http.Agent({ keepAlive: true, maxSockets: 10 }));
})();
A Node.js script that sends 100 sequential requests with and without a keep-alive agent and counts distinct sockets, so connection reuse is measured rather than assumed.
How do you configure connection pooling in undici, fetch and Axios?
Each client exposes pooling through a different object, so the configuration lives in different places.
For Axios in Node, pooling belongs to the core http.Agent and https.Agent. Create one agent per upstream (or per client module) with keepAlive: true, a maxSockets limit on concurrent connections per origin, a maxFreeSockets limit on idle sockets kept warm, and a socket timeout. Pass the agent through Axios's httpAgent and httpsAgent options. Create the agent once and reuse it. If you build a new agent per request, every request gets its own pool, and you lose keep-alive.
undici pools through dispatchers. A Pool targets a single origin, and connections caps its size. An Agent keeps a pool for each origin it sees. Both accept keep-alive and timeout settings such as keepAliveTimeout, headersTimeout and bodyTimeout. You can call pool.request() directly, which is the leanest path. You can also pass the dispatcher to fetch through its dispatcher option, or install it process-wide with setGlobalDispatcher.
| Client | Pool object | Where it's attached |
|---|---|---|
| Axios | http.Agent / https.Agent |
httpAgent / httpsAgent config |
| undici | Pool or Agent |
Used directly |
| fetch | undici dispatcher | dispatcher option or global dispatcher |
The dispatcher option is not part of the fetch standard. Once you use it, your "portable" fetch code depends on undici. It can also break if the undici package you installed is a different version from the one bundled with Node.
Option names and defaults have changed across releases, so check them against the documentation for the Node and library versions you actually run.
// ESM module (top-level await). Verify option names/defaults against your installed Node, axios and undici docs.
// Upstream base URLs come from configuration, e.g. INVENTORY_URL, ORDERS_ORIGIN, BILLING_URL.
import https from 'node:https';
import axios from 'axios';
import { Pool, Agent, fetch, setGlobalDispatcher } from 'undici';
// Axios: one keep-alive agent per upstream, created once and reused
const inventoryAgent = new https.Agent({
keepAlive: true, // reuse sockets instead of reconnecting per request
maxSockets: 50, // cap on concurrent sockets per origin
maxFreeSockets: 10, // idle sockets kept warm
timeout: 30_000, // socket inactivity timeout (ms)
});
export const inventory = axios.create({
baseURL: process.env.INVENTORY_URL,
httpsAgent: inventoryAgent, // use httpAgent for plain http:// upstreams
});
// undici Pool: a single origin, called directly (leanest path)
const orders = new Pool(process.env.ORDERS_ORIGIN, {
connections: 50, // pool size cap
keepAliveTimeout: 10_000,
headersTimeout: 5_000,
bodyTimeout: 10_000,
});
const { statusCode, body } = await orders.request({ path: '/orders/123', method: 'GET' });
const order = await body.json();
// undici Agent: one pool per origin it sees, handed to fetch via `dispatcher`.
// `dispatcher` is not standard fetch; importing fetch from the same undici package
// avoids mixing your undici version with the one bundled in Node.
const agent = new Agent({ connections: 50, keepAliveTimeout: 10_000 });
const res = await fetch(`${process.env.BILLING_URL}/invoices`, { dispatcher: agent });
const invoices = await res.json();
// Or install it process-wide so undici's fetch uses this agent by default
setGlobalDispatcher(agent);
Configuring a reusable keep-alive https.Agent for Axios, an undici Pool used directly, and an undici Agent passed to fetch through the non-standard dispatcher option or installed as the global dispatcher.
How should you set timeouts so a hung upstream cannot stall callers?
A timeout has to be scoped to the phase that can hang. There are three: connect (TCP and TLS handshake), headers (waiting for the status line after the request is sent), and body/idle (the gap between chunks while streaming the response). A single overall deadline cannot cover all three well. A deadline long enough for a legitimate large download lets a dead connect attempt block the caller for the full period. A deadline short enough to catch a dead connect attempt will kill healthy slow streams.
With fetch, pass a signal. AbortSignal.timeout(ms) is the simplest option. It is a single deadline that also applies while you read the body. Use AbortSignal.any to combine it with the caller's own cancellation signal so work stops when the inbound request is abandoned.
Undici exposes per-phase options on its dispatcher (Agent or Pool): connect.timeout, headersTimeout and bodyTimeout. The body timeout measures idle time between chunks, not total transfer time. Use these options alongside a signal for the overall deadline.
Axios has one timeout number, and it does not distinguish between phases. Its exact behaviour depends on the adapter. Add a signal if you need a hard ceiling.
The keep-alive mismatch
Every pooled socket has idle timers on both ends, and on any proxy or load balancer in between. If the server or proxy closes an idle socket first, the client can send a request on it just as the close arrives. That request fails with ECONNRESET or socket hang up. The errors are intermittent and appear mostly after quiet periods. To prevent this, set the client's keep-alive idle timeout (undici's keepAliveTimeout) shorter than every upstream hop's timeout. The client then always closes idle sockets first.
import { Agent, fetch } from 'undici';
// Assumed hop timeouts: upstream server closes idle sockets after 5s,
// the proxy in between after 60s. The client must close idle sockets
// first, so its keep-alive window stays below the smallest of these.
const internalAgent = new Agent({
connect: { timeout: 2_000 }, // TCP + TLS handshake must finish quickly
headersTimeout: 5_000, // request sent -> status line and headers received
bodyTimeout: 10_000, // max idle gap between body chunks, not total transfer time
keepAliveTimeout: 4_000, // idle socket lifetime when the server sends no Keep-Alive hint
keepAliveMaxTimeout: 4_000, // cap, even if the server advertises a longer timeout
});
export async function getItem(itemId, callerSignal) {
// Overall ceiling for the whole call, including reading the body,
// combined with the caller's cancellation (for example, the inbound
// request was aborted) so the work stops as soon as nobody is waiting.
const signal = AbortSignal.any([callerSignal, AbortSignal.timeout(15_000)]);
const res = await fetch(
`${process.env.INVENTORY_URL}/items/${encodeURIComponent(itemId)}`,
{ dispatcher: internalAgent, signal },
);
if (!res.ok) {
await res.body?.cancel(); // release the socket back to the pool
throw new Error(`inventory returned ${res.status}`);
}
// Reading the body is still covered by both bodyTimeout and the signal.
return res.json();
}
An undici Agent with separate connect, headers and body-idle timeouts and a keep-alive window shorter than the upstream hops, used by fetch with a combined overall-deadline and caller-cancellation signal.
Why do unread response bodies exhaust the connection pool?
In undici, a connection is returned to the pool only after the response body has been fully read or explicitly discarded. Until then, the socket still has unread bytes in flight, so it cannot carry the next request. This applies to request() and to the global fetch, which is built on undici. Receiving the status code and headers does not free the connection.
The leak usually hides on error paths. A typical broken handler calls fetch, checks if (!res.ok), and throws an error that includes res.status, but never touches the body. Each failed call holds a socket open. If an upstream starts returning 503s, every one of those responses holds a connection. Once all of the pool's connections are occupied, new requests wait in undici's queue. Callers see rising latency and then timeouts, even though the upstream may already have recovered. Garbage collection may eventually release the sockets, but the timing is unpredictable, and it often comes too late under load.
The fix is to settle the body on every branch. With fetch, call await res.body?.cancel() before throwing, or read the error payload with await res.text() so you can log it. With undici's request(), call await body.dump(), which drains a bounded amount of data and then closes the stream.
Axios avoids this problem because, by default, it reads the whole response into memory before resolving or rejecting. The cost is that a large response is fully held in the heap for each concurrent request. For large payloads, undici's stream() and pipeline() APIs let you write the body directly to a destination, and the connection is released when the stream finishes.
Where should retries live, and when are they unsafe?
None of the three clients should retry a request unless you can prove that sending it twice is harmless. GET, HEAD, PUT and DELETE are idempotent by HTTP semantics, but only if your service actually implements them that way. A POST that charges a card or enqueues a job is not. When a call fails mid-flight, the client cannot tell whether the upstream never received the request or processed it and died before responding.
Stale pooled sockets are the clearest example. If the upstream's keep-alive timeout is shorter than the client's, the client can write to a socket the server has just closed and get ECONNRESET. Retrying is safe for an idempotent request. For a POST, the error looks identical whether or not the server acted on the request. Fix the root cause by keeping the client's idle timeout below the server's. Don't paper over it with retries.
Put retry logic in one place: a thin wrapper around fetch or undici, or an Axios interceptor. That layer should enforce:
- Method and status filters. Retry idempotent methods by default. Retry a
POSTonly when it carries an idempotency key that the server deduplicates. - Exponential backoff with jitter. Without jitter, many callers retry at the same instant.
- A hard attempt cap or retry budget.
Retry at a single layer only. Aggressive timeouts combined with unbounded retries cause trouble. When an upstream slows down, short timeouts fire and each caller resends. The timed-out originals often still complete on the server, so the upstream does duplicate work and repeats side effects at the moment it has the least capacity. If several services in a chain each retry, the extra load multiplies at every hop. That is a retry storm.
Undici vs Axios vs fetch: which should you use, and when should you avoid each?
Each client gives you a different amount of retry, timeout and pooling behaviour to configure yourself.
| Option | Use when | Avoid when | Ergonomics |
|---|---|---|---|
fetch (global) |
Code is shared with browsers or edge runtimes; call volume is moderate | You need per-upstream pool tuning and don't want Node-specific dispatcher options in "portable" code | Standard Response; non-2xx is a normal response you must check |
| undici | Hot internal paths, proxying, streaming large bodies | Code must run outside Node | request, stream, pipeline; explicit pools, low-level |
| Axios | Existing codebase built on interceptors for auth, tracing and logging | New latency-sensitive services | Interceptors, automatic JSON, throws on non-2xx |
Migration has a real cost, and a few percent of client overhead rarely justifies it. In most internal calls, the network and the upstream's own work take far longer than the client's internal processing. Rewriting interceptors and changing error handling from Axios's throw-on-non-2xx model to explicit status checks costs days and introduces bugs. For new code, the trade-off reverses. fetch costs no dependency, and its Response API is already familiar to most engineers. undici's explicit pool settings sit next to the call they affect, so they take less time to debug than defaults hidden behind an extra abstraction layer.
Benchmark against your own upstream before switching. Use these conditions:
- realistic payload sizes
- production-like concurrency
- TLS enabled
- keep-alive configured the same way for every client
Record:
- p99 latency
- open socket count
- throughput
A client that wins on requests per second but opens many more sockets can be the slower choice under production load.
Don't rely on published microbenchmarks for this decision. They usually hit a localhost server with tiny bodies, which mostly measures parsing overhead. That cost rarely dominates real internal traffic.
Who should use which client?
The right choice depends on who owns the code and where it runs more than on raw client speed.
- Teams writing new Node services that make many internal calls should start with undici directly, or with
fetchbacked by an explicitly configured undiciAgent. Typical cases are API gateways, backend-for-frontend layers and fan-out aggregators. These services spend most of their time waiting on other services, so they benefit most from explicit per-upstream pools, per-phase timeouts and streaming. - Teams maintaining code that must also run in browsers, edge runtimes or other JavaScript runtimes should use
fetchand keep Node-specific tuning out of the shared code. Set the global dispatcher once in the Node entry point instead of passingdispatcherat call sites. - Teams with an established Axios codebase should usually stay on Axios. They should still make sure every instance has a shared keep-alive
http.Agentorhttps.Agentand a deliberatetimeout. Most of the latency and reliability gains come from those settings, not from changing libraries. - Platform or infrastructure teams that publish internal client libraries should own the pool, timeout and retry defaults in one shared module. Product teams then inherit sane behaviour without having to tune each call.
If a service makes only occasional outbound calls, the client choice matters little. Use whatever the codebase already uses, with keep-alive enabled.
How can the right client setup save engineering time?
The time savings come mostly from avoiding a class of slow, intermittent problems that are expensive to diagnose. Raw request speed matters less.
- Fewer intermittent-failure investigations. Sporadic
ECONNRESETandsocket hang uperrors after quiet periods are a classic time sink, because they are hard to reproduce. Setting the client keep-alive timeout below every upstream hop's timeout removes the most common cause up front. - No pool-exhaustion incidents from unread bodies. A rule that every branch must consume or cancel the response body prevents slowdowns that look like upstream outages but are really leaked sockets. Encode it in a shared wrapper so individual handlers can't forget it.
- One place to change behaviour. Shared per-upstream client modules hold the agent or dispatcher, the timeouts and the single retry layer. Tuning a pool size or a timeout then means a one-line change in one file, not a search across the codebase.
- Faster diagnosis. Explicit undici
PoolandAgentsettings sit next to the code that uses them. The socket-counting script and thesschecks earlier in this article let you confirm reuse in minutes instead of reasoning about hidden defaults. - Avoiding unnecessary migrations. Measuring pool and socket behaviour before switching libraries often shows that the existing client only needed configuration. That saves the days a rewrite of interceptors and error handling would otherwise take.
- Less upgrade friction. Keeping npm undici objects away from the built-in
fetch, and checking option names against the versions you run, avoids confusing breakage when Node or library versions change.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to undici vs axios, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.