Claude Code stream idle timeout: what it means and what to change

Which message did you see?

Claude Code prints one of these when a model response stops arriving. Each has its own section further down.

API Error: Stream idle timeout - no chunks received

The wording Anthropic's error reference lists. Its find-your-error table sends you to the streaming idle watchdogs section of the network configuration page — where the timers themselves are documented — or to the gateway page's long-thinking section when a Claude apps gateway sits in front.

API Error: Stream idle timeout - partial response received

The wording in the title of an open GitHub issue with 197 reactions. Anthropic's docs do not list it, and the next section covers what that does and does not tell you.

• "partial response received": the wording Anthropic's docs do not list
• Which timer aborted your stream
• What Claude Code tries before it shows you the message
• What actually changes the outcome
• Behind a gateway or proxy

Looking for something else? The Claude Code error messages guide covers the rest, from a prompt that is too long to a login that has expired.

"partial response received": the wording Anthropic's docs do not list

If the message on your screen ends - partial response received, Anthropic's docs do not list that wording. On October 25, 2026 we searched it word for word through Anthropic's Claude Code error reference, its network configuration page, its environment variables reference, its Claude apps gateway deployment page, its API error list and its streaming guide, and it appears in none of them. The same six pages do carry - no chunks received, in three places.

So there is a first-party message of this name, and a second wording that the issue thread reports and that Anthropic has not written down. The open issue on Anthropic's repository carries the second wording:

API Error: Stream idle timeout - partial response received

That issue, #46987, was opened on April 12, 2026 and was still open when we read it on October 25, 2026, with 197 reactions and 184 comments. An automated bot added the duplicate label about a minute after it was filed, so the label records a bot's match rather than a person's triage, and the issue itself stays open. Across all 184 comments, none is from a repository member, owner or collaborator. The reporter's last working version was 2.1.90 and the failing one was 2.1.92.

What that means in practice: Anthropic's docs do not say how the reported wording differs from the documented one. What they document is a timer closing a stream that stopped arriving. Our reasoning, not Anthropic's: the timers below are the ones that do it, so they are where to look either way. What it does not mean is that anybody outside Anthropic can tell you why your particular stream stopped. No repository member has commented in the thread. Anthropic's pages describe the conditions that produce it — a proxy or gateway that transforms or holds the body, a network that drops idle connections, a thinking pause that outlasts a timer — and each one has a documented step, below.

Sources: the six Anthropic pages named above, and issue #46987 with its labels, reaction count, comment count and comment authors, all read October 25, 2026.

Which timer aborted your stream

Claude Code runs four independent timers that abort a streaming model response when it goes quiet. Anthropic's error reference sends this message to that watchdog section rather than naming which of the four fired, so the defaults below are what to compare against your own connection. One timer is documented as ending the turn with a different message, and it is listed first so you can rule it out.

• First-byte deadline. Aborts when no response headers arrive after Claude Code sends the request, so it fires before a response has started, and it ends the turn with a different message: API Error: No response from API. If that is what you saw, the error reference's own entry for it is the one to read. It runs on the direct Anthropic API and Claude Platform on AWS, including through an HTTPS proxy, but not when a base URL routes them through a gateway; it is opt-in in a Claude apps gateway session and on Amazon Bedrock with CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1, and it does not run on Google Cloud's Agent Platform or Microsoft Foundry. The default is 180 seconds on the direct API and 300 seconds on Claude Platform on AWS or Amazon Bedrock, plus one second for every 32KB of request body.
• Event-level watchdog. Aborts when no response events parse. It runs on every provider, at 300 seconds.
• Byte-level watchdog. Aborts when no bytes arrive at all, keep-alive pings included. It runs on the direct Anthropic API, Claude Platform on AWS and gateway connections including a custom base URL, and it is opt-in on Amazon Bedrock. The default is 180 seconds on the direct API and 300 seconds everywhere else it runs.
• Body idle timeout. Aborts when no bytes arrive for five minutes, counting the wait for headers. It applies on providers other than the direct Anthropic API, Claude Platform on AWS and Amazon Bedrock with the byte watchdog turned on.

Two details explain most of the confusing cases. First, where the byte-level watchdog runs on a connection other than Bedrock, arriving bytes including keep-alive pings also reset the event-level watchdog, for a limited time without a parsed event. That grace is about five minutes when bytes arrive at least every 10 seconds, and about 7.5 minutes on a Claude apps gateway's 15-second pings, which is why a stream carrying nothing but pings ends after about 12.5 minutes at the default timeout. A responsive server that is only sending pings can still be cut off.

Second, a stream that had already produced output is reported differently when a timer stops it. Anthropic documents a set of notices for that case, and one of them is the watchdog reporting itself:

API Error: The response stopped arriving. The response above may be incomplete.

If you connect through a gateway base URL, upgrade to v2.1.222 or later. Before it, Claude Code could report a stall on those connections while the server's keep-alive pings were still arriving, because it counted only parsed response events there; upgrading stops those spurious timeouts.

Sources: the streaming idle watchdogs section of Anthropic's network configuration page, and the incomplete-response entry in Anthropic's Claude Code error reference, read October 25, 2026.

What Claude Code tries before it shows you the message

The message is the last thing that happens, not the first. Anthropic's error reference says Claude Code retries transient failures up to 10 times with exponential backoff before showing an error, and that by the time you see one it has already made whatever retries apply to that failure.

While it retries, the spinner carries a countdown. The label in front of it names the specific reason straight away for failures you can act on — a network that is down, a TLS handshake failure, a rate limit — and for every other failure it reads API error until the third attempt, as of v2.1.198:

Retrying in Ns · attempt x/y

A slow stream is announced before it is aborted. After 20 seconds with no data on the response stream the spinner shows this, and the request has not failed yet:

Waiting for API response · will retry in … · check your network

Three version notes matter if the banner seems late or early. Before v2.1.185 it appeared after 10 seconds with different wording. Behind a gateway it appears after 45 seconds without data from v2.1.309, having been 20 seconds before that. And while Claude is consulting the advisor it appears after 90 seconds instead of 20, because a long advisor review can send nothing for well over 20 seconds.

A stall that arrives after Claude has completed a block of text or a tool call, or has started one after finishing its thinking, is deliberately not retried. Anthropic's rule is that re-sending the request could execute the same tool calls twice, so Claude Code keeps what Claude completed, runs any tool calls it finished, and continues the turn from their results. A stall before that point is different: once the headers have arrived and nothing of the response has, or after Claude has finished thinking but has not started text or a tool call, it is aborted and streamed again at most once. A second stall ends the turn with The response stalled before a response was produced only when it comes after Claude has finished thinking and before any text or tool call.

Sources: the automatic retries, "what you see while Claude Code retries or waits", and the waiting-banner notes in Anthropic's Claude Code error reference, read October 25, 2026.

What actually changes the outcome

Every step below is one Anthropic's own pages give, either for a stream that stopped arriving or for the notice you get when it stopped after producing something.

• Raise CLAUDE_STREAM_IDLE_TIMEOUT_MS. It sets both watchdogs' timeout, and Claude Code raises a value below five minutes to five minutes. The byte-level watchdog caps the value at 30 minutes.
• Set CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS instead when only the byte-level watchdog needs longer. It is clamped to between 10 seconds and 30 minutes and takes precedence over the shared variable for that watchdog.
• Turn one watchdog off rather than lengthening it. CLAUDE_ENABLE_STREAM_WATCHDOG and CLAUDE_ENABLE_BYTE_WATCHDOG force the matching timer on with 1 or off with 0, and neither extends a timer to a connection type it does not already cover.
• Set API_FORCE_IDLE_TIMEOUT to 0 to turn the body idle timeout off, or to 1 to turn it on for every provider. The watchdogs run independently of it, so a stream that needs to pause longer than their thresholds needs them raised or disabled too.
• When you have the incomplete-response notice in an interactive session, reply continue so Claude picks up from its last completed block. Claude Code keeps every block that finished, but discards an interrupted final block, so the last sentences or tool calls may be missing. In a non-interactive run, when the cut-off response is in the main conversation and contains text but no tool calls, Claude Code asks Claude to continue on its own, up to three times in a row, before you see the notice. A subagent's reply is continued whether the session is interactive or not, on the same text-but-no-tool-calls condition, with no count given.

One adjustment looks like it shortens the wait and lengthens it instead. Setting CLAUDE_STREAM_IDLE_TIMEOUT_MS below 300000 is raised to 300000, and because that variable sets both watchdogs' timeout, on the direct Anthropic API it takes the byte-level watchdog from its 180-second default up to 300 seconds, so a quiet stream fails later rather than sooner. If you need one to fail sooner instead, the clamp that allows it belongs to CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS, which runs from 10 seconds to 30 minutes — but unless CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS is set as well, that same value also becomes the first-byte deadline wherever that deadline runs. API_TIMEOUT_MS does not do it either: it limits the wait for response headers, and the byte-level watchdog starts only once those headers arrive, so a response that stalls after them follows the stalled-stream rules instead of that deadline.

One thing Anthropic's step lists do not offer is a restart, and it is worth ruling out because it gets tried. Our reasoning, not Anthropic's: the message describes a stream that has already ended rather than state held in the session, so a fresh process has nothing to clear.

Sources: the streaming idle watchdogs and no-response-from-api sections of Anthropic's network configuration page and Anthropic's Claude Code error reference, and the stream timeout rows of Anthropic's environment variables reference, read October 25, 2026.

Behind a gateway or proxy

If every request through a gateway fails this way, the gateway is doing something to the stream, and Anthropic documents two distinct failures with different fixes.

The first is an empty stream. A response completes without delivering usable data, and Claude Code re-sends the request without streaming to finish the turn, showing this once per session in interactive sessions only:

Streaming response ended before any complete data was received. Retrying without streaming. If this keeps happening, check any proxy or gateway between Claude Code and your model provider.

Anthropic names the cause for that one directly: a proxy or gateway that consumes or transforms the streaming response body on the way back. The fix is to configure it to pass streaming response bodies and their headers through unmodified.

The second is long thinking, and it is the one that produces the stream idle timeout by name. Claude Code's debug log records it like this:

Error streaming, falling back to non-streaming mode: Stream idle timeout - no chunks received

What happens is a sequence. A stream delivers message_start and then only pings while Claude thinks. With default settings on a gateway whose upstream is not the Anthropic API, Claude Code ends that stream after about 12.5 minutes, then sends the same request without streaming, and those requests get no pings, so a slow reply hits the proxy's timeout and comes back as a run of 504 errors. On a gateway whose upstream is the Anthropic API, the long request ends after about 20 minutes and the requests after it fail with a 502 from the gateway, or the proxy's 504 when the proxy times out first.

Anthropic's answer is one change: raise CLAUDE_STREAM_IDLE_TIMEOUT_MS and pick a value that covers your longest thinking pause, starting at 1800000 if you do not know it. A stream can stay on pings alone for about 7.5 minutes longer than the value you set, so at the default of 300000 that is about 12.5 minutes, at 900000 about 22.5, and at 1800000 about 37.5. On an Anthropic API upstream the same choice is about 20 minutes at the default, 30 at 900000 and 45 at 1800000. Raising the proxy's timeout alone does not work, because the requests without streaming still fail once a reply takes longer than Claude Code's own wait of 300 seconds.

If CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK is set to 1, there are no requests without streaming to observe, and the turn ends with API Error: Stream idle timeout - no chunks received instead. Anthropic notes that setting also helps when a fallback is causing the same tool calls to run twice.

A third form is worth knowing because no timer is involved in it. Anthropic's API can send an error event inside a stream, such as an overloaded_error that would be a 529 outside one, and the API error list says a mid-stream failure does not follow the standard HTTP handling. Separately, some networks drop idle connections after a variable period, which Anthropic names as a reason a request can fail or time out without a response.

Sources: the two long-thinking sections of Anthropic's Claude apps gateway deployment page, the empty-stream entry in Anthropic's Claude Code error reference, the error events section of Anthropic's streaming guide, and the long-requests section of Anthropic's API error list, read October 25, 2026.

Running several sessions at once

When a stream dies in one of a row of sessions, the work does not have to stop there. Omniscio, the desktop app we make for running many Claude Code sessions at once, notices when the CLI abandons a response mid-flight and replays your last message to restart the turn: a background scan runs every 60 seconds, and each session gets two automatic retries a day. While it recovers, the session looks like a normal running session, and that invisibility is capped at five minutes before it surfaces with a Retry button while the scan keeps retrying. It is on by default, and Settings → Sessions carries an Aborted-response recovery switch that turns the automatic retries off. The aborted-response recovery page documents all of it, including what happens after the two retries are spent.

Two neighbouring cases are documented separately, because they look the same from a chair and are not the same thing. A session whose CLI stops producing output past the stall-detection time turns orange with the label "Stalled?", neither an error nor a question, and the default time is 15 minutes: the stalled session page has that one. A turn that stops with the context window near-full is continued automatically, bounded at three nudges: the out-of-context stall recovery page has that one.

Two guides cover the surrounding work: running multiple Claude Code sessions and running many coding agents at once. The features page lists the rest, and the download page has the installers.

Sources

Every message, default and step above rests on one of these, and the date beside each is the day we read it.

• Claude Code error reference, for the message, the retry rules, the incomplete-response notices and the waiting banner. Read October 25, 2026.
• Network configuration, for the four streaming idle watchdogs, their defaults and the variables that change them. Read October 25, 2026.
• Environment variables, for each stream timeout variable's floor, cap and precedence. Read October 25, 2026.
• Claude apps gateway deployment, for the two long-thinking failures and the debug-file line. Read October 25, 2026.
• Anthropic API errors, for mid-stream error events and idle connection drops. Read October 25, 2026.
• Streaming messages, for the error event the API can send inside a stream. Read October 25, 2026.
• Issue #46987, for the "partial response received" wording, its state, labels, reactions and comments. Read October 25, 2026.

Anthropic's error reference and environment variables reference move with nearly every Claude Code release and keep notes such as "Before v2.1.309" and "Before v2.1.222". Read them again before you trust a copy of this page from a few months back.

Common questions

Is "Stream idle timeout - partial response received" a Claude Code message?

Anthropic's Claude Code error reference lists a stream idle timeout message, worded API Error: Stream idle timeout - no chunks received. The wording partial response received appears in none of the six Anthropic pages this guide rests on, and we searched each one word for word on October 25, 2026. It is the wording in the title of an open GitHub issue carrying 197 reactions, so people are reporting it, but Anthropic's documentation does not describe it.

Which timer actually aborted my response?

Anthropic's error reference sends this message to the streaming idle watchdogs rather than naming which timer fired, so the defaults are what to compare against your connection. The event-level watchdog aborts when no response events parse and runs on every provider at 300 seconds. The byte-level watchdog aborts when no bytes arrive at all, keep-alive pings included, and is 180 seconds on the direct API. A body idle timeout of 5 minutes applies on the other providers. The one timer documented as a different error is the first-byte deadline: it fires before a response has started and ends the turn with 'No response from API' instead.

Does setting CLAUDE_STREAM_IDLE_TIMEOUT_MS to a low number make it fail faster?

No. Below 300000 it is raised to 300000, so at best nothing changes, and on the direct Anthropic API it makes the byte-level watchdog slower, from 180 seconds to 300. If you need one to fail sooner, the clamp that allows it belongs to CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS, which runs from 10 seconds to 30 minutes — but unless CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS is set as well, that same value also becomes the first-byte deadline wherever that deadline runs. Lowering API_TIMEOUT_MS does not do it either, because it limits the wait for response headers and the byte-level watchdog starts only once those headers arrive.

Will restarting Claude Code clear a stream idle timeout?

Anthropic's docs do not list a restart as a step. Our reasoning, not Anthropic's: the message describes a stream that has already ended rather than state held in the session, so a fresh process has nothing to clear.

Why did I get "The response above may be incomplete" instead of a timeout message?

Because the stream died after Claude had already produced something. When a stalled stream is aborted after Claude has completed a block of text or a tool call, Claude Code does not re-send the request, since that could run the same tool calls twice. It keeps what was completed and appends an incomplete-response notice, and one of that notice's variants, The response stopped arriving, is the streaming idle watchdog reporting itself. The step Anthropic gives for that notice, in an interactive session, is to reply 'continue' so Claude picks up from its last completed block; Claude Code keeps every block that finished but discards an interrupted final block, so the last sentences or tool calls may be missing. In a non-interactive run, when the cut-off response is in the main conversation and contains text but no tool calls, Claude Code asks Claude to continue on its own, up to three times in a row, before the notice appears. A subagent's reply is continued whether the session is interactive or not, on the same text-but-no-tool-calls condition, with no count given.