[DOCS] Environment variable docs are outdated for stalled stream recovery behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/env-vars

Section/Topic

CLAUDE_ENABLE_STREAM_WATCHDOG, CLAUDE_STREAM_IDLE_TIMEOUT_MS, and CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK

Current Documentation

The env var reference currently says:

CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK | Set to 1 to disable the non-streaming fallback when a streaming request fails mid-stream. Streaming errors propagate to the retry layer instead. Useful when a proxy or gateway causes the fallback to produce duplicate tool execution

CLAUDE_ENABLE_STREAM_WATCHDOG | Set to 1 to abort API response streams that stall with no data for 90 seconds. Useful in automated environments where a hung session would go unnoticed, or behind proxies that drop connections silently. Without this, a stalled stream can hang the session indefinitely since the request timeout only covers the initial connection. Configure the timeout with CLAUDE_STREAM_IDLE_TIMEOUT_MS

CLAUDE_STREAM_IDLE_TIMEOUT_MS | Timeout in milliseconds before the streaming idle watchdog closes a stalled connection. Default: 90000 (90 seconds). Requires CLAUDE_ENABLE_STREAM_WATCHDOG=1. Increase this value if long-running tools or slow networks cause premature timeout errors

What's Wrong or Missing?

Changelog v2.1.105 says:

Improved stalled API stream handling: streams now abort after 5 minutes of no data and retry non-streaming instead of hanging indefinitely

But the env var page still describes stalled-stream protection as an opt-in watchdog with a 90-second default and says non-streaming fallback applies when a streaming request fails mid-stream.

That leaves the current docs outdated or unclear on the user-visible behavior after v2.1.105:

A. Default behavior is unclear

The docs imply stalled streams still hang indefinitely unless CLAUDE_ENABLE_STREAM_WATCHDOG=1 is set.

B. The timeout value is unclear

The docs say the default idle threshold is 90 seconds, while the changelog says stalled streams now abort after 5 minutes of no data.

C. Fallback interaction is unclear

The docs do not explain whether CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 disables this new stalled-stream recovery path, or only the older mid-stream failure fallback.

Suggested Improvement

Update env-vars to explain the post-v2.1.105 behavior explicitly:

• State whether the 5-minute no-data abort + non-streaming retry is now the default behavior
• Clarify how CLAUDE_ENABLE_STREAM_WATCHDOG and CLAUDE_STREAM_IDLE_TIMEOUT_MS interact with that default
• Clarify whether CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 disables the retry path after a stalled stream
• Distinguish idle no-data handling from other request timeouts so users know which knob applies to which failure mode

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/env-vars | Primary documentation for the stalled-stream watchdog and non-streaming fallback behavior |

Total scope: 1 page affected

Source: Changelog v2.1.105

Exact changelog entry: Improved stalled API stream handling: streams now abort after 5 minutes of no data and retry non-streaming instead of hanging indefinitely