Claude Code “Stream idle timeout – no chunks received”: Which Variable to Raise and What Does Not Work (Tested)

Short answer: API Error: Stream idle timeout - no chunks received is not an Anthropic server error. It is Claude Code’s own watchdog ending a response stream that went silent. Raise CLAUDE_STREAM_IDLE_TIMEOUT_MS, and, if you do not know how long your longest pause is, start at 1800000 (30 minutes), the starting value in Anthropic’s Claude apps gateway docs (that page is written for gateway setups). I tested the timers against a mock server that goes silent. Two things surprised me: values below 300000 were silently raised to 300 seconds, and the exact wording I saw on Claude Code 2.1.312 and 2.1.319 was different from the documented one. Details and logs are below.

What the error means

Claude Code streams the model’s answer. To avoid hanging forever on a dead connection, it runs timers that abort a stream that stops delivering data. According to Anthropic’s network configuration docs, there are four of them:

Timer	Aborts when	Default
—	—	—
First-byte deadline	No response headers arrive after the request is sent (direct API and some other connections)	180 s on the direct Anthropic API
Event-level watchdog	No response events can be parsed	300 s
Byte-level watchdog	No bytes at all arrive, pings included	180 s direct API; 300 s through a custom ANTHROPIC_BASE_URL
Body idle timeout	No bytes for 5 minutes (on providers other than the direct API)	5 minutes

The documented error text for this case is API Error: Stream idle timeout - no chunks received, listed in Anthropic’s error reference. The typical cause in the docs is a gateway or proxy in the path: only keep-alive pings flow while the model thinks for a long time.

What I saw when I made a stream go silent (tested)

I wrote a small mock server that answers a Claude Code request with HTTP 200, sends the opening message_start event, and then says nothing. I ran claude -p "say hi" against it with ANTHROPIC_BASE_URL pointing to the mock and a made-up API key:

Setting	What happened
—	—
CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS=10000	Second request exactly 10 s after the first; final output API Error: stream idle: no bytes for 10000ms (2.1.312 and 2.1.319)
Same, but the mock also sent some text first	Same result: retry after 10 s, then the same API Error: stream idle: no bytes for 10000ms in -p mode
CLAUDE_ENABLE_BYTE_WATCHDOG=0 and CLAUDE_STREAM_IDLE_TIMEOUT_MS=10000	No failure at 10 s. New request every 300 s; after two attempts (600 s) the run ended with Request timed out
CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS=15000 set only in a project .claude/settings.json under env	Retry exactly 15 s later, so the settings file route works

Three honest notes. First, I did not reproduce the exact documented string Stream idle timeout - no chunks received; on these versions the byte-level watchdog printed stream idle: no bytes for 10000ms instead. Your message may differ by version and connection type. Second, my mock is not the real API. Third, I ran everything in non-interactive -p mode, so I did not see the interactive “response above may be incomplete” notice.

The fix: raise the timeout

The docs’ recommendation is to raise CLAUDE_STREAM_IDLE_TIMEOUT_MS to cover your longest pause. Put it in your shell profile:

export CLAUDE_STREAM_IDLE_TIMEOUT_MS=1800000

or in the env block of your settings file (my test used the same mechanism with the byte-level variable):

{"env": {"CLAUDE_STREAM_IDLE_TIMEOUT_MS": "1800000"}}

Where the settings file lives is explained in Claude Code settings.json location. Rules from the docs:

• CLAUDE_STREAM_IDLE_TIMEOUT_MS sets both the event-level and byte-level timeouts. Claude Code raises any value below 300000 (5 minutes) to 300000, and caps the byte-level one at 30 minutes. I confirmed the raise: 10000 acted as 300 s in my second test.
• CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS changes only the byte-level watchdog, from 10 seconds to 30 minutes, and needs Claude Code 2.1.210 or later.
• API_TIMEOUT_MS limits how long Claude Code waits for response headers, not how long a stream may go quiet afterwards, so it is not the fix here.
• A longer timeout also means a really dead connection takes longer to notice.

Things that do not work the way they look

• Lowering the variable does not make it fail sooner. Because of the 300000 floor, setting 60000 should give you 300 s on the event-level watchdog (the docs say so, and my 10000 test behaved that way). If you want a faster failure, use the byte-level variable (10 s minimum).
• Turning a watchdog off is not a fix. The docs say CLAUDE_ENABLE_STREAM_WATCHDOG=0 and CLAUDE_ENABLE_BYTE_WATCHDOG=0 switch the timers off, and a dead connection then has no early exit. I did not test a real hang beyond the two timeouts above.
• The proxy has its own timeout. If your gateway or reverse proxy closes idle connections sooner than Claude Code does, raising the Claude Code value alone changes nothing. Raise the proxy’s timeout as well.

Check the network side

The docs’ usual suspect is a gateway, proxy or VPN that holds the connection while the model thinks. A GitHub issue (anthropics/claude-code #70217) describes a user whose ISP’s NAT dropped connections that sat idle for a few seconds; I did not verify that report. If the error appears only on one network, test from another one before you change timers.

Related messages

This error is different from “streaming response ended before any complete data”, from 529 overloaded and from “unable to connect to API”. More are in the Claude Code error list.

FAQ

Is Anthropic’s API down when I see this?

Not necessarily. The error comes from the timer inside Claude Code. It tells you the stream went quiet for longer than the timer allows, whatever the reason.

What do I do right after the error?

In an interactive session the docs say to reply continue; Claude Code keeps every block that finished and drops an interrupted last one. I did not test this.

Will a bigger value slow down normal use?

No. The timer only matters when a stream goes silent. It decides how long Claude Code waits before giving up.

Sources and test notes

• Anthropic docs: Network configuration, “Streaming idle watchdogs” (code.claude.com/docs/en/network-config); Error reference (code.claude.com/docs/en/errors); Environment variables (code.claude.com/docs/en/env-vars).
• Tested myself: Claude Code 2.1.312 and 2.1.319 on Linux against a mock server that goes silent, with CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS, CLAUDE_STREAM_IDLE_TIMEOUT_MS with the byte watchdog off, and a settings-file env entry.
• Not tested: the real Anthropic API, gateways, Bedrock, interactive mode, the exact documented error string, continue behavior.