›_ Claude Code Issues
Claude Code Issues / #69147

[DOCS] Connection-drops section omits that partial responses are preserved and the spinner no longer gets stuck at "running tool" (v2.1.179)

Open 💬 0 comments Opened Jun 17, 2026 by coygeek

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/errors

Section/Topic

"Network and connection errors" section under "Find your error" → "Network and connection errors", particularly the "Unable to connect to API" subsection and the cross-cutting "Automatic retries" section. The spinner/UI-recovery behavior also touches "Status indicators" in interactive-mode.md and the "Spinner behavior" notes in settings.md.

Current Documentation

The "Automatic retries" section says:

"Claude Code retries transient failures before showing you an error. Server errors, overloaded responses, request timeouts, temporary 429 throttles, and dropped connections are all retried up to 10 times with exponential backoff. While retrying, the spinner shows a Retrying in Ns · attempt x/y countdown."

The "Unable to connect to API" subsection (the entry point for "Network and connection errors") only describes initial-connection failures and their recovery:

"The TCP connection to the API failed or never completed. ``text Unable to connect to API. Check your internet connection Unable to connect to API (ECONNREFUSED) Unable to connect to API (ECONNRESET) Unable to connect to API (ETIMEDOUT) fetch failed Request timed out. Check your internet connection and proxy settings ` Common causes include no internet access, a VPN that blocks api.anthropic.com`, or a required corporate proxy that is not configured."

The spinner-related behavior settings (in settings.md rows 285-287) only describe cosmetic spinner tips/verbs and accessibility options, not the spinner-UI recovery on connection drop.

What's Wrong or Missing?

A. The mid-stream connection-drop behavior is undocumented

Changelog v2.1.179 says:

"Fixed mid-stream connection drops: partial responses are now preserved instead of showing a raw error, and the spinner no longer gets stuck at 'running tool'"

The docs at https://code.claude.com/docs/en/errors cover initial-connection failures and pre-retry status, but do not describe what users see when the connection drops after a response has started streaming. The new behavior is:

  • Assistant text that was already streamed is preserved on the screen and in the session history (instead of being replaced by a raw error string).
  • The spinner is reset when retries are exhausted on a mid-stream drop, rather than freezing on the "running tool" verb.

This is a user-visible behavior change that the error reference and the "Automatic retries" section do not mention.

B. "Dropped connections" in the Automatic retries section reads as connection-establishment failures

The current sentence groups "dropped connections" with the other transient retry cases, but the only drop case the rest of the page explains is Unable to connect to API (the connection-never-completed case). There is no documentation of a drop that occurs mid-stream after some response bytes have already arrived.

C. The "running tool" spinner verb is not documented anywhere

spinnerVerbs and prefersReducedMotion are documented as customization knobs, but the default verb "running tool" (the literal text the spinner would freeze on before v2.1.179) is not described as a documented state anywhere in the docs. After the fix, users hitting the old behavior have no doc to compare against; users on the new code have no doc explaining why the spinner now resets.

Suggested Improvement

Add a new subsection under "Network and connection errors" titled "Connection drops mid-stream" (or extend "Unable to connect to API") that states:

  • A connection drop after the API has started streaming a response is treated as a transient error and goes through the normal [Automatic retries](#automatic-retries) flow.
  • If retries are exhausted, the already-streamed assistant text remains visible and is kept in the session transcript; users do not see a raw error string replacing it.
  • The spinner is reset to the idle state once retries are exhausted on a mid-stream drop, rather than continuing to display "running tool".
  • Recovery: re-send the same prompt, or use /rewind to step back to the last checkpoint and continue from there.

Suggested placement in errors.md:

### Connection drops mid-stream

The network connection to the API broke after the response had already started streaming. This is distinct from [Unable to connect to API](#unable-to-connect-to-api), which is a failure to establish the connection in the first place.

**What to do:**

* Wait for Claude Code to finish the automatic retry countdown shown in the spinner. Up to 10 attempts are made with exponential backoff.
* If retries are exhausted, the assistant text that was already streamed stays on the screen and remains part of the session transcript. You do not see a raw error replacing it.
* The spinner resets once retries are exhausted. Re-send your prompt to continue, or run `/rewind` to step back to the last checkpoint.
* If the same prompt keeps dropping mid-stream, check the recovery steps under [Unable to connect to API](#unable-to-connect-to-api) — the network, proxy, or VPN cause is usually the same.

Also add one sentence to the "Automatic retries" intro to call out the post-retry partial-response behavior:

"When the connection drops mid-stream (after some response bytes have already arrived) and retries are exhausted, the already-streamed assistant text is preserved and the spinner is reset rather than displaying a raw error. See [Connection drops mid-stream](#connection-drops-mid-stream)."

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/errors | 63 (Automatic retries), 411-443 (Network and connection errors) | Primary location: post-retry partial-response and spinner-reset behavior on mid-stream connection drops |
| https://code.claude.com/docs/en/interactive-mode | n/a | Status indicator / spinner state changes after a mid-stream drop |
| https://code.claude.com/docs/en/settings | 274, 285-287 (spinner settings) | Default spinner behavior vs spinnerVerbs after a mid-stream drop |

Total scope: 3 pages affected

Source: Changelog v2.1.179

Changelog entry: "Fixed mid-stream connection drops: partial responses are now preserved instead of showing a raw error, and the spinner no longer gets stuck at 'running tool'"

Notes:

  • The earlier issue for SDK/print-mode partial-response preservation on user interruption (covering v2.1.94) is intentionally out of scope: that issue is about the SDK/claude -p surface and user-initiated interrupts, while this one is about the interactive UI surface and a network-initiated mid-stream drop. The two fixes land in different code paths and have different user-visible error states, so they should remain separate issues.
  • The env-vars "CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK" and API_FORCE_IDLE_TIMEOUT knobs are related to the same failure surface but are documented separately, so they are not the right home for this change either.

View original on GitHub ↗