A long request deadline does not stop undici's bodyTimeout from killing a stream that goes silent. Loopback measurements of headersTimeout, bodyTimeout and an AbortSignal deadline.
A request that dies at exactly five minutes
A model streaming a long answer usually sends a steady trickle of chunks. A model writing one very large tool-call argument, such as a whole document passed to a file-writing tool, may send nothing for minutes, then everything at once. If the HTTP client has a timeout on silence, that turn fails at the silence limit no matter how long the overall request deadline is.
Gemini CLI issue 29747 describes exactly this: with a long silent tool call, the client's body timeout was fixed at 300 seconds for API-key authentication, and the turn was dropped and replayed. Pull request 30258, merged on 12 November 2026, changes the CLI's global fetch configuration so that bodyTimeout scales with a configured request timeout larger than the 300-second default, keeping 300 seconds as a floor. At the time of writing the newest Gemini CLI releases are v0.68.0 and v0.69.0-preview.0, both published on 10 November, so the fix is merged but not yet in a release. The pull request's description is the source for its behaviour here; this guide explains the underlying mechanism in Node.js's undici HTTP client and measures it.
Three timeouts, three questions
undici, the HTTP client behind Node.js's built-in fetch, has several timeouts, and each answers a different question. Its client documentation defines them:
connectTimeout: how long to wait to establish the socket. Default 10 seconds.headersTimeout: how long the parser waits to receive the complete HTTP response headers. Default 300 seconds.bodyTimeout: how long to wait while receiving body data, monitoring the time between consecutive body chunks. Default 300 seconds.
None of them is a deadline for the whole request. For that, you pass an AbortSignal, typically AbortSignal.timeout(ms), which aborts the request when it fires, wherever it is.
The trap is that people configure the deadline and assume it governs everything. It does not. A request with a 15-minute deadline and the default body timeout still fails after 5 minutes of silence in the body. That is the situation in the Gemini CLI issue: its configuration path raised the headers timeout, but the body timeout stayed a module constant at 300 seconds. The fix sets the body timeout to the larger of 300 seconds and the configured request timeout, or to an explicit value if one is given.
A loopback measurement
The companion example starts a local HTTP server that imitates a model stream for the fictional Belgavi's Book Store support agent: it sends response headers, one chunk ("Drafting the reply for CASE-9120"), then goes silent for a configurable time, then sends the final chunk. A probe calls it with undici 7.30.2 from npm under Node.js 22.17.0, with times scaled down from minutes to hundreds of milliseconds so the run takes seconds.
case result
300 ms silence, bodyTimeout 1 s complete
1.5 s silence, bodyTimeout 1 s UND_ERR_BODY_TIMEOUT
1.5 s silence, headersTimeout 3 s, bodyTimeout 1 s,
deadline 3 s (only the headers raised) UND_ERR_BODY_TIMEOUT
1.5 s silence, bodyTimeout 3 s, deadline 3 s complete
1.5 s before headers, headersTimeout 1 s UND_ERR_HEADERS_TIMEOUT
1.5 s silence, both 3 s, deadline 0.8 s TimeoutError (deadline)The third row is the shape of the bug: the request deadline and the headers timeout are generous, the body timeout is not, and the body timeout wins. The fourth row is the shape of the fix.
One more observation from the run: the timers fired late. A 1-second body timeout fired after about 1.2 seconds in one run and 1.5 seconds in another. The undici documentation warns about this: parser timeouts are not guaranteed to fire with exact millisecond precision, and delays above one second use lower-overhead timers with a target resolution around 500 milliseconds. Do not write tests that depend on a timeout firing within a few milliseconds.
Configuring it
With the npm package, pass a dispatcher:
import { Agent, fetch } from 'undici';
const modelDispatcher = new Agent({
connectTimeout: 10_000,
headersTimeout: 120_000, // wait for complete response headers
bodyTimeout: 900_000, // longest silence we accept mid-stream
});
const res = await fetch(url, {
method: 'POST',
body,
dispatcher: modelDispatcher,
signal: AbortSignal.timeout(900_000), // the whole request
});setGlobalDispatcher changes the default for every fetch in the process, which is what Gemini CLI does. That is convenient but broad: every other HTTP call in the process, including ones to services that should fail fast, inherits a fifteen-minute silence tolerance. A dedicated dispatcher for model traffic keeps the long limits where they belong.
Note that Node.js's built-in fetch bundles its own copy of undici; on Node.js 22.17.0 it reports 6.21.2 in process.versions.undici. The npm package version and the bundled version can differ, and options are applied by whichever dispatcher the call actually uses.
Choosing the numbers
Each timeout should come from what you know about the other side.
The headers timeout bounds the wait for complete response headers; the first byte alone does not establish that those headers are complete. For a model API, that is the time to accept the request and start streaming, which depends on queueing and prompt size. It can be generous, but it should not be the full deadline, because a server that has not sent headers after several minutes is usually stuck.
The body timeout bounds the longest gap you consider healthy. For token streaming, gaps are normally short. For models that think before answering, or that emit one large tool argument at the end, they can be long. Provider guidance matters here; the Gemini CLI issue cites Google's Gemini migration checklist recommending client timeouts of at least 15 minutes. Prefer a server that sends keep-alive events during long silences, which turns a silence problem into a non-problem, over an ever-longer body timeout.
The deadline bounds what the user will wait for and what you will pay for. Set it from the product, and make sure the body timeout is not shorter than the longest legitimate silence within that deadline.
What the pull request changes, and what it leaves
According to its description, pull request 30258 replaces the hard-coded body timeout with a module default backed by a 300-second constant, and makes updateGlobalFetchTimeouts(timeoutMs, bodyTimeoutMs) set it to bodyTimeoutMs when given, otherwise to Math.max(300000, timeoutMs). An explicit value must be a positive finite number, or the function throws a RangeError. The new values are applied to the global undici agent, the safe agent used for guarded requests, and the proxy agents. It also makes an empty proxy string clear the current proxy and restore the standard global agent, so proxy state does not leak between reconfigurations. Its validation steps suggest setting model.requestTimeoutMs to 900000, or the GEMINI_API_HEADERS_TIMEOUT_MS environment variable, and checking that both timeouts become 900000.
Two things follow for users of any tool built this way. Raising one setting now raises both limits together, which is usually what you want. And the floor means you cannot shorten the body timeout below five minutes through that path; a deliberately short silence limit needs the explicit parameter.
Retries and replays
The issue says the timed-out turn was replayed. A body timeout mid-stream means some output may already have been shown and some tokens already billed. Retrying the whole request is safe only if the client discards the partial attempt, including any tool calls it contained, and the user is told. Count body timeouts separately from other errors, because a spike in them after a model change is a configuration signal, not an outage.
Failure modes
- A deadline raised to match the provider's guidance while the body timeout stays at its default.
- A global dispatcher change that makes unrelated calls hang for minutes.
- A proxy agent created with its own defaults, bypassing the timeouts set on the global agent; the Gemini CLI pull request updates its proxy agents alongside the global one for this reason.
- Tests that assert a timeout fires at an exact millisecond.
- A retry after a mid-stream timeout that duplicates output already shown.
Verify it
Run the companion probe and tests. For your own client, start a local server that holds the body silent for longer than your body timeout and shorter than your deadline, and assert which error you get; then raise the body timeout and assert the request completes. Run the same test through any proxy configuration you support.
Run the example yourself
The loopback server and probe for headersTimeout, bodyTimeout and an overall deadline with undici 7.30.2 pinned, and two node --test tests. Companion code on GitHub; its README lists the prerequisites, exact commands, expected output and limits.