Claude’s stream idle timeout means the response stopped arriving before the client finished waiting. Start by preserving partial work, retrying a smaller task, and changing one setting or condition at a time; repeated retries can consume usage without resolving the interruption.
The message API Error: Stream idle timeout - partial response received has been reported in Claude Code, the Claude web app, the desktop app, and the mobile app.
A clear troubleshooting sequence helps you separate a stalled response, a demanding task, and a connection problem.
What a stream idle timeout means in Claude
Claude normally delivers a response in small pieces rather than waiting until the entire answer is complete. An idle timeout occurs when those pieces stop arriving for longer than the client allows.
“Partial response received” means some output arrived before the interruption. It doesn’t mean the task completed, that files were saved correctly, or that repeating the request will pick up at the right place.
If the failure appears as JSON, stream_idle_timeout identifies the error type. The supplied error also includes statusCode: 500, needsRetry: true, and “The model stopped responding. Please try again.”
That retry flag is a recovery suggestion, not a promise that another attempt will succeed.
Before continuing a coding task, review the partial response and any changed files. A connection failure doesn’t tell you whether an earlier operation completed. Identifying completed work helps prevent duplicated edits and gives the next request a clear starting point.
Why Claude stops responding mid-task
A GitHub bug report describes failures on Claude Code versions 2.1.177, 2.1.178, and 2.1.179. The reporter reproduced them with Haiku, Sonnet, and Opus across all context sizes.
The report separates two patterns that deserve different troubleshooting decisions.
A response starts, then goes silent
In the mid-stream failure, approximately 5 KB of output arrived normally. The server then sent nothing for 180 seconds, after which the client’s byte-watchdog aborted the stream.
A byte-watchdog monitors incoming response data. When nothing arrives within its waiting period, it ends the request rather than leaving the session open indefinitely.
This pattern explains why a task can appear productive before suddenly failing. Partial progress doesn’t rule out a delivery problem. It also means shortening the prompt may help organize recovery without necessarily addressing the underlying stall.
Nothing arrives before a connection error
The same reporter said roughly 1 in 4 requests received no response chunk for 30 seconds or more. Many eventually failed near an 8-minute client timeout with undefined Connection error.
That observation describes one reported environment, not a failure rate for all Claude users. It also doesn’t establish why the first response was delayed.
Record whether the request stalled before any output or after a partial response. The distinction is more useful than grouping every interruption under the same error message.
Start with smaller tasks and controlled retries
A focused retry gives you a clearer result than immediately repeating the entire assignment. We recommend changing one condition per attempt so you can identify what helped.
Reduce the task and preserve completed work
Split a large request into clear stages: analysis, a proposed change, implementation, and review. For longer reasoning, git operations, or LaTeX report generation, ask for one stage at a time.
Use /compact when a long conversation is making the next request difficult to manage. Reddit users reported mixed results; it helped one user and didn’t help another.
Other reported workarounds include running a writing task in a subagent or using a small Python script under 200 lines. These are task-management options, not confirmed repairs for a stalled connection.
Choose an approach that fits the assignment. A script is useful for repeatable document assembly, while a subagent can keep a writing task separate from a larger conversation. Neither needs to become part of every retry.
Compare models and clients carefully
Switching from Opus to Sonnet helped some Reddit users, while others reported no improvement. Another user encountered the error across all models and contexts.
Client comparisons were also mixed. Some users said the Claude Code CLI succeeded when the browser and mobile apps timed out. Other reports placed the error across several Claude interfaces.
Keep the task as similar as possible when comparing models or clients. Otherwise, a successful attempt may reflect a smaller assignment rather than the change you intended to test.
There are no measured workaround success rates in these reports. Treat them as practical options, with results that depend on the situation.
Adjust the reported local timeout setting
One Reddit user reported that extending the stream idle timeout resolved their failures. The change is a local CLI setting, not a setting for the browser, desktop, or mobile apps.
Add the reported value without replacing other settings
The reported workaround sets CLAUDE_STREAM_IDLE_TIMEOUT_MS to 600000 inside the env block of ~/.claude/settings.json.
For a settings file containing only this entry, the structure is:
{"env":{"CLAUDE_STREAM_IDLE_TIMEOUT_MS":"600000"}}
If your file already contains settings, preserve them. Add the variable to the existing env object rather than replacing the file or creating a second env block. Keep the JSON syntax valid, including commas between existing entries.
The value is in milliseconds. 600000 milliseconds equals 10 minutes. Restart the CLI before trying the same focused task again.
Understand what a longer wait changes
A longer idle allowance gives an interrupted stream more time to resume. It doesn’t make the server respond sooner, reduce task complexity, or repair a broken network connection.
The positive result came from one user’s report. Other users may still encounter a stall or a different timeout.
A ten-minute stream idle allowance doesn’t establish that the separate eight-minute connection timeout has changed.
If nothing resumes during the longer wait, return to a smaller task or collect evidence. Increasing the value repeatedly offers little useful diagnostic information.
Separate network clues from proxy settings
Connection evidence can narrow the problem, but it needs careful interpretation. A stalled stream doesn’t automatically mean your Wi-Fi failed, and an open connection doesn’t guarantee that response data is arriving.
What the network capture showed
The GitHub reporter captured an 8-second tcpdump with zero packets while the socket remained ESTABLISHED with empty queues. They interpreted this as server-side silence.
That observation supports a delivery stall during the capture. It doesn’t prove which service or network component caused it.
Routing traffic through a Tailscale exit node reportedly eliminated the mid-stream stalls, but didn’t fix the slow-first-byte failures. Changing the egress source IP affected one reported pattern without resolving both.
If you compare network paths, keep the task consistent and record which failure changes.
Why Envoy and AWS timeout advice is different
Search results also include proxy documentation with similar terminology. Envoy lists default timeouts of 5 minutes for stream idle, 1 hour for HTTP idle, 15 seconds for a route, and 5 seconds for a connection.
AWS Application Load Balancer has a 60-second default idle timeout. Istio guidance describes setting the downstream gateway slightly higher, such as 65 seconds.
These values belong to infrastructure configuration. They don’t describe the reported 180-second client watchdog, and changing an EnvoyFilter isn’t a supported fix for this client error.
Unless you administer a proxy in the request path, keep your troubleshooting focused on Claude, the task, and the connection you use.
Know when to stop and report the error
Stop repeating the full assignment when failures continue across controlled attempts. A useful report describes the conditions, timing, and partial output, not just that Claude stopped responding.
Collect the following details:
- Record the installed client version, operating system, model, and interface where the failure occurred.
- Include the exact error text and whether any response arrived before the interruption.
- Note the time until the first output, the length of the silent period, and the approximate time until failure.
- Describe the task, conversation size, and relevant operations without exposing private files or credentials.
- Include available request IDs, relevant logs, and the changes tried, along with each result.
Request IDs help correlate a failed session with server logs. The GitHub reporter provided them alongside socket observations and offered additional logs.
Before sharing diagnostics, remove secrets and unrelated personal information. A concise, reproducible description is more useful than a large collection of unfiltered output.
Users also reported that failed sessions consumed several percent of weekly usage before erroring. That figure is anecdotal, but it gives you a practical reason to avoid repeated full-task retries.
Save the evidence, preserve completed work, and submit a bug report if the same failure continues.
Frequently asked questions
Can a long prompt cause this error?
A large assignment can make recovery more difficult, so smaller stages are a sensible first step. However, the GitHub reporter reproduced the error across all context sizes and several models.
Prompt length alone doesn’t explain those observations. Record whether the failure follows a particular operation or also appears during a short request. That comparison helps distinguish a task-related pattern from a broader delivery problem without assuming either cause.
Does needsRetry: true mean I should keep retrying?
It means the error response recommends another attempt. It doesn’t state that the previous work was rolled back, that the next request will succeed, or that retries won’t consume usage.
Review the partial output first, then retry a limited unfinished stage. If the same interruption returns under controlled conditions, preserve the timing and request details instead of repeatedly launching the entire assignment.
Resume work with a clear recovery plan
A reliable response to Claude’s stream idle timeout starts with preserving progress and identifying when the stream stopped. Smaller tasks and controlled comparisons give you useful information without repeating unnecessary work.
The reported ten-minute setting may help a mid-stream stall, but its success remains anecdotal. When the failure persists, a report with version details, timing, request IDs, and partial-output evidence gives the issue a clearer path toward investigation.