[DOCS] `API_FORCE_IDLE_TIMEOUT` opt-out for the Vertex/Foundry 5-minute idle timeout is undocumented

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The "Environment variables" reference table (alphabetical) and the Vertex AI / Microsoft Foundry provider pages. The new API_FORCE_IDLE_TIMEOUT environment variable, and the new default 5-minute idle timeout that v2.1.169 restored on Vertex and Foundry, are both missing from the docs.

Current Documentation

The Environment variables reference documents the existing idle-watchdog knobs but does not list API_FORCE_IDLE_TIMEOUT anywhere. The closest related entries today are:

CLAUDE_ENABLE_STREAM_WATCHDOG — Set to 1 to enable the event-level streaming idle watchdog. Off by default. Applies to all providers, including Bedrock. For Vertex and Foundry, this is the only idle watchdog available. On Bedrock, you can also enable the independent byte-level watchdog with CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK; the two run together when both are set. 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 and minimum 300000 (5 minutes) for both the byte-level and event-level watchdogs; lower values are silently clamped to absorb extended thinking pauses and proxy buffering. For third-party providers, requires CLAUDE_ENABLE_STREAM_WATCHDOG=1. On Bedrock, also applies when CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1

The Google Vertex AI and Microsoft Foundry provider pages do not mention a default idle timeout or the API_FORCE_IDLE_TIMEOUT=0 opt-out. Grep across the entire docs/code.claude.com mirror for API_FORCE_IDLE_TIMEOUT returns the changelog entry as the only hit.

The v2.1.169 changelog says:

Restored a default 5-minute idle timeout on Vertex/Foundry so a stalled stream aborts instead of hanging indefinitely; set API_FORCE_IDLE_TIMEOUT=0 to opt out

What's Wrong or Missing?

A. New env var not in the env-vars reference

API_FORCE_IDLE_TIMEOUT is a public environment variable (the changelog tells users to set it), but it is missing from the Environment variables alphabetical table. Users on Vertex/Foundry who see a stalled stream abort after 5 minutes and want to opt out have no documented knob to reference.

B. Existing idle-watchdog docs are not updated to reflect the new Vertex/Foundry default

The current CLAUDE_ENABLE_STREAM_WATCHDOG row says "Off by default" and "For Vertex and Foundry, this is the only idle watchdog available." As of v2.1.169, Vertex and Foundry now have a 5-minute idle timeout on by default — that is no longer accurate. The "off by default" framing contradicts the new behavior, and the relationship between the existing opt-in event-level watchdog and the new Vertex/Foundry default is unexplained.

C. Vertex AI and Microsoft Foundry pages do not mention the default timeout or opt-out

The provider pages (Google Vertex AI and Microsoft Foundry) are the natural place a Vertex/Foundry user would look for behavior that is unique to that provider. Neither page mentions the 5-minute idle timeout, the reason it was reintroduced, or the API_FORCE_IDLE_TIMEOUT=0 escape hatch. Users who hit the new abort have no way to discover the opt-out from the provider pages.

Suggested Improvement

Option A: Comprehensive fix

1. Add an API_FORCE_IDLE_TIMEOUT row to the env-vars table, alphabetized (it falls between ANTHROPIC_VERTEX_PROJECT_ID and BASH_DEFAULT_TIMEOUT_MS):

API_FORCE_IDLE_TIMEOUT — When set to 0, disables the default 5-minute idle timeout on Vertex AI and Microsoft Foundry, so a stalled stream does not abort automatically. Off-by-default timeout exists because the previous "no timeout" behavior could hang indefinitely; set this opt-out to restore the old behavior. Added in v2.1.169. See Google Vertex AI and Microsoft Foundry.

1. Update the CLAUDE_ENABLE_STREAM_WATCHDOG row to note that Vertex and Foundry now have a separate on-by-default 5-minute idle timeout, distinct from the opt-in event-level watchdog, controlled by API_FORCE_IDLE_TIMEOUT.

1. Add a short "Idle timeout" section to the Google Vertex AI and Microsoft Foundry pages noting that a stalled stream on these providers aborts after 5 minutes by default (v2.1.169) and that API_FORCE_IDLE_TIMEOUT=0 opts out.

Option B: Minimum fix

Add the API_FORCE_IDLE_TIMEOUT row to the env-vars table and a one-line note in the Vertex AI and Microsoft Foundry pages. Leave the existing CLAUDE_ENABLE_STREAM_WATCHDOG row as-is for now and address the overlap in a follow-up.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/env-vars | Missing API_FORCE_IDLE_TIMEOUT row; CLAUDE_ENABLE_STREAM_WATCHDOG row no longer accurate for Vertex/Foundry |
| https://code.claude.com/docs/en/google-vertex-ai | Missing default 5-minute idle timeout mention and opt-out |
| https://code.claude.com/docs/en/microsoft-foundry | Missing default 5-minute idle timeout mention and opt-out |
| https://code.claude.com/docs/en/changelog | Source of the new behavior (v2.1.169 entry) |

Total scope: 4 pages affected (1 env-vars table + 2 provider pages + 1 changelog cross-reference).

Version: v2.1.169 restored this default. The previous "no timeout" behavior could hang indefinitely; the new opt-out (API_FORCE_IDLE_TIMEOUT=0) restores that prior behavior for users who want it.

Related: A separate, broader env-vars staleness report covers other stream-recovery variables. This issue is scoped to the new API_FORCE_IDLE_TIMEOUT opt-out and the restored Vertex/Foundry 5-minute default. If the two turn out to overlap, merge into a single env-vars staleness issue.