How Do You Fix a Stream Idle Timeout in Claude Code?

Last updated: 2026-10-29 by Ted Sellers, Owner

A stream idle timeout means the client or an intermediary stopped receiving data before its silence limit expired. In Claude Code, start by preserving completed work, splitting the request, and testing a smaller response; increase a timeout only after identifying which layer closed the stream, because client, proxy, and provider limits operate independently.

When This Applies

Which errors belong to this troubleshooting process?

This applies to API Error: Stream idle timeout - partial response received and application responses marked as a stream-inactivity timeout.

A response may also include statusCode: 500, needsRetry: true, and "The model stopped responding. Please try again." Those fields classify the failure as retryable. They don’t identify the component that stopped sending data.

Reports cover Claude Code and Claude interfaces accessed through the web. A Claude Code Web issue describes responses stopping midway through generation. The visible error alone cannot establish whether the fault belongs to the application, connection, or provider.

When should you investigate something else?

Authentication failures, exhausted account limits, invalid requests, and failed tool commands require separate troubleshooting. A compiler error during LaTeX generation isn’t a streaming timeout unless the connection also stops delivering data.

The same distinction applies to local commands. A stalled Git operation can hold up an agent without proving that the model connection failed.

Before changing settings, preserve the exact message and identify whether any response arrived. That separates first-byte delay from a mid-stream stall, which require different investigations.

What Causes a Stream Idle Timeout?

Why can a long request fail midway?

A streaming response sends data incrementally. An idle timer measures silence between qualifying activity, rather than the total time spent completing the job.

Users report failures during large writes, Git tasks, LaTeX report compilation, and planning-agent steps. These reports establish recurring circumstances, not a single verified cause.

One GitHub report describes an established connection receiving no server data for 180 seconds before a byte-watchdog aborts it. That is one observed failure pattern, not a documented universal Claude Code default.

How does slow first-byte behavior differ?

The same report describes roughly one in four requests waiting at least 30 seconds for initial data. Some requests reportedly end around an eight-minute client limit with undefined Connection error.

Those observations describe different timing boundaries. A request that never starts streaming cannot be diagnosed solely as a pause between response chunks.

Claude Code timeout reports also show why a persistent connection doesn’t prove useful progress. A socket can remain established while no application data arrives.

Record the delay before the first response separately from the silence after the last received chunk.

Step-by-Step

Recover without repeating completed actions

1. Save the error, timestamp, selected model, and last successful action. Record whether the failure happened before output or midway through it.
2. Inspect changed files and command results before retrying. A partial response doesn’t mean earlier writes, commits, or external actions were rolled back.
3. Resume at the first unfinished task. Ask for one bounded result, such as one file edit or one analysis step, rather than repeating the entire request.
4. Separate generation from execution. Finish the document or code change first, then run compilation, tests, or Git operations as distinct steps.

Reduce the request and isolate the failure

5. Run /compact when a long session has accumulated substantial context. Preserve requirements and unfinished work before continuing.
6. Split large writes into smaller sections. Users reporting this error describe chunked requests as a workaround, although success doesn’t identify the original fault.
7. Switch from Opus to Sonnet and repeat a small, comparable task. Treat success as evidence that behavior changed, not proof that either model caused the connection problem.
8. Try a bounded write through a subagent if the workflow supports it. Reported successes are anecdotal; a subagent doesn’t bypass every shared connection or provider limit.
9. Stop repeated blind retries if the same failure returns. Keep the smaller test case and move to timing and connection diagnosis.

Can You Change Claude Code’s Stream Idle Timeout?

What does CLAUDE_STREAM_IDLE_TIMEOUT_MS change?

Users report setting the variable to 600000 in ~/.claude/settings.json. That value equals 10 minutes.

The reported configuration places the variable inside the existing env object: {"env":{"CLAUDE_STREAM_IDLE_TIMEOUT_MS":"600000"}}.

Merge the entry into the existing file. Don’t replace unrelated settings or create a second conflicting env object. Restart Claude Code, then repeat the same bounded task.

A GitHub workaround report discusses this variable and a longer value of 1800000, or 30 minutes. These are user reports. They don’t establish an Anthropic-supported setting, a guaranteed default, or compatibility across releases.

When will a longer timeout fail to help?

Increasing a client timer cannot override an earlier proxy or provider cutoff. A ten-minute client allowance won’t preserve a connection that an intermediary closes after one minute.

It also won’t correct invalid credentials, a failed tool process, or an upstream service that has stopped making progress.

A longer timeout buys waiting time. It doesn’t prove the stream is healthy or make completed actions safe to repeat.

Change one setting at a time. Compare the elapsed failure time and whether output resumes. If nothing changes, restore the previous setting rather than stacking undocumented adjustments.

Keep an upper limit on unattended retries, especially when the task can modify repositories or call external services.

How Do You Identify the Failing Connection Layer?

Measure the request at three points

Record request start, first received data, and last received data. Then record the disconnect.

A long gap before initial output points toward connection setup, upstream queuing, or first-byte handling. A repeatable gap after output begins can point to a TCP idle timeout or an application-level stream stall.

Compare several attempts. A consistent elapsed boundary is stronger evidence of a configured limit than one unusually slow response.

One report found no packets arriving while TCP remained established. Changing the route through a Tailscale exit node reportedly removed the mid-stream stalls. That suggests path sensitivity in that case, but doesn’t establish a general fix.

Separate client, proxy, and provider evidence

Repeat a small request through a second approved network path. Keep the model and task unchanged so the comparison remains useful.

If you operate a gateway, correlate its access logs with the client timestamp. Look for the terminating hop, response status, reset reason, and upstream duration.

Envoy’s downstream_cx_idle_timeout and upstream_cx_idle_timeout counters track connection closures caused by idle timeouts. Inspect the appropriate counters through /stats or exported Prometheus metrics.

These are connection-level counters. A stream can time out without either counter explaining the event, so include stream-reset details.

Remove tokens, cookies, and sensitive prompt content before sharing logs or captures.

Which Envoy Timeout Settings Affect Streaming?

Which timer measures which part of the connection?

Envoy’s timeout documentation separates connection inactivity, stream inactivity, route completion, and connection establishment.

These defaults apply to Envoy, not automatically to Claude Code.

Setting	Default	What it measures
HTTP stream-inactivity limit	5 minutes	No qualifying activity on a stream
HTTP connection idle_timeout	1 hour	Connection inactivity without active requests
TCP proxy (tcp_proxy) idle_timeout	1 hour	No data through the proxied TCP connection
Route timeout	15 seconds	Time allowed for the complete upstream response
Cluster connect_timeout	5 seconds	Upstream connection establishment, including TLS handshake

A reported 180-second Claude failure doesn’t match Envoy’s five-minute stream default. That mismatch prevents a reliable diagnosis based on defaults alone.

The tcp_proxy timer controls the TCP idle timeout, which measures data inactivity on the proxied connection.

Which settings should change for streaming APIs?

For open-ended streaming responses, disable the route timeout with timeout: 0s. This request timeout covers the complete upstream response, even if data continues to arrive.

Keep a deliberate stream-inactivity limit. stream_idle_timeout 0s disables that protection, which can leave abandoned streams consuming resources.

Changing connect_timeout won’t fix a stall after streaming begins; it controls the connection timeout, including the TLS handshake. Extending HTTP connection idle time won’t necessarily change a stream’s silence allowance.

For Kubernetes gateways, HTTPRoute timeout controls distinguish request and backend-request budgets. Don’t assume those controls configure an Envoy stream-idle watchdog.

How Do Istio, ALB, and MuleSoft Affect the Timeout?

How should Istio and load-balancer limits interact?

Istio can expose several timeout controls, but they apply at different layers. A DestinationRule connection-pool idleTimeout, an HTTP connection manager stream-inactivity limit, and a per-route idle_timeout aren’t interchangeable.

An AWS Application Load Balancer defaults to a 60-second idle timeout. An Istio example uses a 65-second gateway timeout to place that boundary above the load balancer’s limit.

That ordering doesn’t prevent the ALB from closing a silent connection at 60 seconds. The application must deliver qualifying activity in time, or the ALB’s allowance must also change.

If a connection uses WebSocket, transport keepalives don’t necessarily mean application data has arrived. Visible interface activity may not reset the stream timer.

Why can accepted configuration still have no effect?

An older Istio 1.2.5 case involved an EnvoyFilter written for a newer API version. The object existed, but the intended TCP idle-timeout change didn’t affect the running proxy.

Inspect the effective proxy configuration rather than treating object creation as proof that a patch applied.

MuleSoft’s Stream Idle Timeout policy uses seconds, defaults to 300, and returns 504 when stream inactivity exceeds its limit.

A wrapper reporting HTTP 500 therefore doesn’t automatically identify MuleSoft, Envoy, or any other intermediary. Capture the upstream status and gateway logs before assigning the failure to a particular product.

Where multiple gateways exist, document each silence limit separately. The earliest applicable cutoff controls the request.

Frequently Asked Questions

Can I recover the missing part of a partial response?

You can preserve text already received, but the error doesn’t guarantee that the missing portion is recoverable. Inspect files and tool results before continuing. Resume with the unfinished section rather than asking the agent to repeat completed actions.

Will switching models change the quality of my unfinished work?

It can change the response and reasoning approach. Give the replacement model the requirements, accepted decisions, and remaining task. Review the continued work against those requirements instead of assuming it will reproduce the previous model’s intended answer.

What happens if I increase the timeout to 30 minutes?

If the client recognizes the setting, it may wait longer before aborting an idle stream. An earlier gateway cutoff still applies. Longer waits also delay failure detection, so use them only where extended silence is acceptable.

Can a timeout cause duplicate commits or external actions?

The timeout itself doesn’t duplicate actions. Retrying an entire workflow can repeat operations that already succeeded before the connection failed. Inspect repository history, changed files, and external operation results before restarting a task with side effects.

What should I include in a useful bug report?

Include the client version, operating system, model, exact error, and a minimal reproducible task. Add first-byte delay, last-data time, and total elapsed time. State whether the failure persists across sessions or approved network paths, and attach sanitized logs without credentials or private project content.

Conclusion: Match the Fix to the Timer

Recover the work before extending the wait

A stream idle timeout identifies a period without expected data. It doesn’t identify the failed component or tell you which earlier actions completed.

Preserve the partial response, inspect side effects, and resume the smallest unfinished task. That gives you a controlled recovery attempt and reduces the amount of work exposed to another interruption.

Model switching, /compact, chunked writes, and subagents are reported workarounds. Treat their results as observations rather than proof of a root cause.

Change only the limit supported by the evidence

Separate first-byte delay, mid-stream silence, route completion, and connection establishment before adjusting settings. Each timer covers a different failure condition.

A longer client allowance can help only when that client timer is the limiting factor. Use measured timing and the terminating hop to choose the next change, while keeping retries bounded and completed work intact.