Skip to content
AI Dev Toolkit.
Esc
  • Loading…

Claude Code · Certificates and network

API Error: Stream idle timeout - partial response received

“Stream idle timeout - partial response received” means Claude’s reply stopped arriving partway through. How to keep the partial work, continue and prevent it.

Message

The exact error

Claude Code
API Error: Stream idle timeout - partial response received

Also appears as:

Current CLI wording
API Error: The response stopped arriving. The response above may be incomplete.
CLI, before v2.1.227
Response stalled mid-stream
Before any text or tool call was produced
The response stalled before a response was produced

Meaning

What does “Stream idle timeout - partial response received” mean?

Claude’s replies arrive as a stream. Claude Code runs watchdog timers that abort a stream when it goes quiet, so a dead connection fails instead of hanging for ever. A stream idle timeout means the response had started, then no data arrived for longer than the watchdog allows, so Claude Code closed it. This exact wording is what people report from Claude Code on the web, the Desktop app and older CLI versions; the current CLI says “The response stopped arriving. The response above may be incomplete.” Either way, what was completed before the stall is kept, and Claude Code doesn’t re-run the request automatically, because that could run the same tool calls twice.

Causes

Why does the response stall?

  • A very long single output, such as one huge Write or Edit tool call; GitHub reports (#50534) describe it repeating on long Write and Edit calls
  • A proxy, VPN or gateway that buffers the stream or drops idle connections
  • Heavy load on the API that slows a long response
  • On gateways reached through ANTHROPIC_BASE_URL, versions before v2.1.222 could report spurious timeouts while keep-alive pings were still arriving

Fix

How do I fix a stream idle timeout?

  1. Reply “continue”

    In an interactive session, read what’s on screen, then send continue. Claude picks up from its last completed block. The final interrupted sentence or tool call may be missing, so check the last file it was writing.

  2. Ask for smaller pieces

    If it happens on large outputs, ask Claude to write one file or one section per reply, or to make several small edits instead of rewriting a whole file. Shorter outputs finish well inside the watchdog’s limit.

  3. Update Claude Code

    Run claude update. Several versions changed how stalls are detected and reported, including a fix in v2.1.222 for gateway connections.

  4. Behind a slow proxy or gateway, raise the watchdog timeout

    Set CLAUDE_STREAM_IDLE_TIMEOUT_MS (in milliseconds) to give a stalled stream longer before it’s closed. Values under 5 minutes are raised to 5 minutes, and the byte-level watchdog caps it at 30 minutes. You can put it in the env block of your settings file so every session uses it.

    macOS / Linux, 10 minutes
    export CLAUDE_STREAM_IDLE_TIMEOUT_MS=600000
    claude
    ~/.claude/settings.json
    {
      "env": {
        "CLAUDE_STREAM_IDLE_TIMEOUT_MS": "600000"
      }
    }

Explained

What happens in -p scripts and subagents?

In non-interactive runs (-p, the Agent SDK and cloud sessions), when the cut-off reply contains text but no tool calls, Claude Code keeps the partial output and asks Claude to continue by itself, up to three times in a row, before it reports the error. Subagents do the same. With --output-format json, the message appears in the result field; resume the session and send continue once the connection is stable.

A stream that never starts at all is a different error: see No response from API. For settings that persist across sessions, the settings.json builder writes a valid env block.

FAQ

Questions people ask

Do I lose my work after a stream idle timeout?

No. Claude Code keeps every block Claude completed before the stall and runs any tool calls that finished. Only the interrupted final block is dropped, such as the last sentence or a half-written tool call. Reply continue to have Claude carry on, and check the last file it was editing.

What is the default stream idle timeout in Claude Code?

Claude Code runs several watchdogs. On the direct Anthropic API the byte-level watchdog closes a connection after 180 seconds with no bytes at all; on Claude Platform on AWS and through a custom base URL it’s 300 seconds. CLAUDE_STREAM_IDLE_TIMEOUT_MS sets the event- and byte-level timeouts, with a 5-minute minimum.

Why does the stream idle timeout happen on Claude Code on the web?

Claude Code on the web runs the same agent in a cloud session, so long replies or large file writes can stall the same way. Reports on GitHub show it most on long, multi-step responses. Ask for smaller pieces, reply continue after it happens, and check status.claude.com if it starts suddenly for many sessions at once.

Should I turn the stream watchdog off?

Usually not. Without it, a dead connection can hang a session for a long time instead of failing and letting you continue. If a slow proxy is the cause, raise CLAUDE_STREAM_IDLE_TIMEOUT_MS instead. CLAUDE_ENABLE_STREAM_WATCHDOG=0 does turn the event-level watchdog off, but keep that for diagnosing a problem.

Related

Search all Claude Code errors

Keep exploring