AI coding tool errors

• An error occurred during streaming

  Did any output arrive before the error? That one test splits this generic string into two unrelated failures — only one is reachable by your retry setting.

• anthropic.APIConnectionError: Connection error

  A typed exception with a constant message. What __cause__ holds, and why where it was raised decides whether the SDK already retried twice or not at all.

• API Error: Claude's response exceeded the 32000 output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable

  Output tokens are a different budget from the context window, so /compact fixes nothing — when to raise CLAUDE_CODE_MAX_OUTPUT_TOKENS and when to split the work.

• api error: connection closed mid-response

  Why a streamed response dies halfway through in AI coding tools, why your SDK's retry never sees it, and how to tell a client-side timeout from an upstream overload.

• API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation

  Why a broken tool_use/tool_result pair makes every later turn fail with the same 400, why retrying or restarting can't clear it, and what /rewind changes.

• API Error (503 no healthy upstream) · Retrying in 1 seconds… (attempt 1/10)

  A 503 that is not in the vendor's documented error table, so it never reached the model — why there is no request id, and what the retry counter hides.

• API Error: Rate limit reached

  Four different limits print this one line. How to tell an ordinary 429 from a monthly spend cap, and why trimming the prompt usually changes nothing.

• API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited

  The parenthetical is the whole message: no quota is drained, so no reset will save you. What server-side throttling reacts to and the one lever that clears it.

• API Error: Stream idle timeout - partial response received

  An idle timeout measures the gap between chunks, not total duration — why big requests aren't the culprit, what your partial output proves, and when to retry.

• API Error (Connection error.) · Retrying in 1 seconds… (attempt 1/10)

  The counter is the CLI's own loop, not your SDK's — and its presence rules out a certificate failure. When to let it run, and when ten attempts prove nothing.

• API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"},"request_id":"req_011CZrhgdwV7TvN3achye98d"}

  A 500 that reached the service and left a request id: whether retrying is safe, when a repeating 500 is your payload, and what the id is actually for.

• API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"OAuth authentication is currently not supported."}}

  A 401 that means your credential type is wrong for the endpoint, not that your login failed — why re-running /login returns it, and which setting to look at.

• API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.71.content.8: `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response."},"request_id":"req_011CUQZ6ttKtJbU8JQRYyizo"}

  Only the last assistant turn is frozen — earlier ones you may edit freely. Why stripping thinking blocks to save tokens breaks the next request, and how to recover.

• API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages: text content blocks must contain non-whitespace text"},"request_id":"req_011CXnuVCF3KmwzeqdM4gFNZ"}

  An empty text block the API itself produced is illegal to send back. Why this message names no index, why trimming makes it worse, and how to find the block.

• API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"The request body is not valid JSON: no low surrogate in string: line 1 column 410559 (char 410558)"}}

  Half a character — a split emoji — makes every later turn fail the same way. Why no retry, model switch or /compact clears it, and how to find it from the offset.

• API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools.48.custom.name: String should have at most 64 characters"}}

  The measured name is not the one you wrote — a server prefix eats your budget. Why renaming the MCP server beats renaming the tool, and how to find index 48.

• API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits."}}

  A billing stop delivered as a 400 payload error. Why subscribers see it while owing nothing, why no retry handler catches it, and which money limit refused you.

• API Error: Usage credits required for 1M context

  A capability gate, not an exhausted quota. Why the tool asked for the 1M window without you, why buying API credits is the wrong fix, and how to stay under it.

• ✗ Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code

  Why Claude Code cannot replace its own files, why the npm command it prints fails for the same reason, and how to fix the global install without sudo.

• bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted

  Not a network problem: the kernel refused a capability in a new namespace. How to tell restricted user namespaces from a container profile, and what each fix costs.

• bwrap: Unknown option --argv0

  Bubblewrap rejected a flag before your command ran. Why the binary is old rather than the flag wrong, why apt will not help on LTS, and what to change instead.

• ChatCompletionMessageToolCallParam "cannot instantiate typing.Union"

  Not an API error: a Python TypeError raised before a request exists. Why the SDK's *Param names were never constructors, and why pinning the old release re-arms it.

• codex/sandbox-state-meta missing sandboxPolicy

  It names the sandbox but nothing was denied: a record reached a consumer without a required field. Why loosening your sandbox settings cannot fix a version mismatch.

• Compaction failed unexpectedly

  Why the generic compaction failure is usually not a length problem, where the real error is hiding, and why running /compact again is attempt eleven.

• Error code: 400 - {'error': {'message': "Invalid parameter: 'tool_calls' cannot be used when 'functions' are present

  One request carrying two generations of the tool interface. Why the conflicting fields come from different layers, and why deleting tool_calls makes it worse.

• Error creating task Invalid request: AbsolutePathBuf deserialized without a base path

  A relative path crossed a boundary with no working directory. Why `~` counts as relative, how to find the value without guessing at the tool's internals.

• Error: ENOENT: no such file or directory, scandir 'C:\ProgramData\ClaudeCode\.claude\skills'

  Why this ENOENT points at a legacy Windows path, why creating the folder fixes nothing, and how it differs from spawn node ENOENT.

• Error: Error during compaction: API Error: Usage credits required for 1M context · turn on usage credits at claude.ai/settings/usage, or use --model to switch to standard context

  The rescue call needs the tier that just refused it, and the suggested model switch hits a second wall. The one exit left costs no model call at all.

• Error: Error during compaction: Error: Conversation too long. Press esc twice to go up a few messages and try again

  Why /compact fails on the conversation it was meant to shrink, why double-Esc looks broken when your input box isn't empty, and how to break the deadlock.

• Error: Failed to spawn Claude Code process: spawn node ENOENT

  ENOENT after spawn means a program was not found on PATH, not that a file is missing. Why `claude` working in your terminal proves nothing about what failed.

• Error: File content (28375 tokens) exceeds maximum allowed tokens (25000). Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content

  One file read refused locally, before anything was sent. Why the ceiling sits far below your context window, and why reading the file whole never sticks.

• Error in hook callback hook_0: Error: Tool permission stream closed before response received

  Your permission callback never answered, and the turn moved on without it. How to work out which hook hook_0 is, and what one retry tells you about the cause.

• ERROR Invalid Version: 2.1.0 (2026-01-07)

  A semver parser rejected a version string you never typed. How to find which program produced it, which program parsed it, and why the CLI cannot repair itself here.

• {"error":{"message":"You exceeded your current quota, please check your plan and billing details.","type":"insufficient_quota","param":null,"code":null}}

  OpenAI sends this body for several different budget and pacing limits, and the field that would tell them apart is null. Where the answer actually is.

• Error: Permission to use WebSearch has been auto-denied in dontAsk mode

  Not a failure — a policy decision made by the session you launched. How to find what put you in that mode, why the run kept going anyway, and what to change.

• Error: Remote Control is not enabled for your account. Contact your administrator

  An entitlement answer, not a bug — and the administrator it names may not exist. How to check which account is being asked, and what to request from whom.

• Error: Response payload is not completed

  The client was promised more bytes than arrived — the framing broke, not just a socket. Which constant, bytes or seconds, names the hop that cut the body.

• Error running remote compact task: stream disconnected before completion: error sending request for url (https://chatgpt.com/backend-api/codex/responses/compact)

  Compaction is the largest request your session ever sends, and failing it leaves you at maximum context — why running it again is the one move that reliably fails.

• Error: Sibling tool call errored

  A placeholder, not a diagnosis: another call in the same parallel batch failed. How to find the real error in the transcript, and why this call may still have run.

• Error: Timeout waiting after 1000ms

  One second is too short to be an API call. What a 1000 ms wait really is, why raising the request timeout does nothing, and how flaky differs from deterministic.

• ImportError: cannot import name 'TypeAliasType' from 'typing_extensions'

  Not an OpenAI error: a resolution failure at import time. Why the file path in the message is the diagnosis, and why upgrading the package re-arms the bug.

• [hyperv] failed to mount Plan9 share "c": Plan9 mount failed: invalid argument

  Why this is a mount negotiation failure rather than a permissions one, how to tell a host-side regression from your own config, and why elevating fixes nothing.

• Installation failed Failed to fetch version from stable: AxiosError: timeout of 30000ms exceeded

  The installer stalled on a version lookup, not a download. Why a timeout means something dropped your packets, and why npm's proxy settings do not apply here.

• Invalid API key · Please run /login

  Why a successful /login can be followed immediately by Invalid API key, how a stray ANTHROPIC_API_KEY shadows your subscription, and what /status settles.

• MaxFileReadTokenExceededError: File content (31252 tokens) exceeds maximum allowed tokens (25000). Use offset and limit parameters to read specific portions of the file, or search for specific content instead of reading the whole file

  The file-read ceiling as a thrown exception class. How to tell whether your run died or adapted, why a retry loop here is silent and fast, and what to catch on.

• MCP client for `X` failed to start: handshaking with MCP server failed: connection closed: initialize response

  The pipe closed while Codex waited for the initialize response, so no tool has been exchanged yet. Why stdout, not your config, is the usual culprit.

• MCP error -32000: Connection closed

  The code tells you the pipe closed, never why. How to recover the phase the message threw away — startup crash, mid-session death, or a server that exits idle.

• Missing API key · Run /login

  Why this is a credential-resolution failure, not a rejected key, why /login is unavailable in the non-interactive runs that cause it most, and what to check.

• MCPContentTooLargeError: MCP tool "read_file" response (30206 tokens) exceeds maximum allowed tokens (25000). Please use pagination, filtering, or limit parameters to reduce the response size

  The tool worked and the client threw the result away. Why an MCP response is charged for every turn after it lands, and which half of the fix is yours.

• No response from API · Retrying in 2m 25s · check your network

  A retry interval in minutes means backoff already escalated. How to read silence versus a labelled API error, what being retried rules out, and when the loop ends.

• OAuth error: fetch failed

  An auth-labelled network error: no response ever arrived, so no credential was involved. Why the browser working proves nothing, and which host to test.

• OAuth error: Request failed with status code 500

  Why a status code proves your network worked, how to tell a vendor fault from a proxy forging the 500, and why restarting the login beats retrying it.

• OAuth error: timeout of 15000ms exceeded

  Why this fixed login deadline is not the API timeout you can configure, why a network that browses fine still fails it, and what actually shortens the path.

• openai.error.AuthenticationError: <empty message>

  The class comes from the status code, the message from the body. A blank message means the 401 body was not OpenAI's — so look at what answered, not your key.

• openai.RateLimitError: Error code: 429 insufficient_quota

  The exception class is picked from the status code, so RateLimitError names every 429. What to catch, what to branch on, and why the retry already happened.

• prompt is too long: 209117 tokens > 200000 maximum

  The count moves, the cause usually doesn't: tool definitions and system content fill the window before your chat does, and compaction cannot remove them.

• openai.BadRequestError: Error code: 400 - {'error': {'message': "This model's maximum context length is 16385 tokens. However, your messages resulted in 16648 tokens. Please reduce the length of the messages.", 'type': 'invalid_request_error', 'param': 'messages', 'code': 'context_length_exceeded'}}

  Catching it, reading the numbers out of it, and deciding reshape versus model swap. Why parsing the message is the brittle move and a trimming loop can diverge.

• RPC error -1: failed to ensure virtiofs mount: Plan9 mount failed: bad address

  Why -1 tells you nothing, why naming both virtiofs and Plan 9 means the fallback failed too, and why bad address points at version skew rather than your config.

• openai.error.APIConnectionError: Error communicating with OpenAI: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))

  No status line ever arrived, so key and quota are irrelevant. Why this one exception means opposite things before and during a stream, and what to catch.

• stream disconnected before completion: failed to parse ErrorResponse: invalid type: null, expected struct Error

  Two failures stacked: the stream died, then the error body would not deserialize. What a null where a struct was expected proves about who actually answered you.

• stream disconnected before completion: Your input exceeds the context window of this model. Please adjust your input and try again

  Not a network failure — a size verdict wearing a network prefix. Whether any output arrived first tells you if the overflow was there at submit or grew mid-turn.

• ⚠️ stream error: error sending request for url (https://chatgpt.com/backend-api/codex/responses); retrying 1/5 in 182ms…

  The request never reached the endpoint, so no status exists to look up. What the named host tells you about which hop failed, and why fast retries prove little.

• Streamable HTTP error: Failed to open SSE stream: Not Found

  A 404 is an answer, so the server is not down and your network is fine. How to tell the server's own 404 from an intermediary's, and why one retry is the test.

• tools: Tool names must be unique

  Two servers exposing the same tool name is almost never the cause — prefixes prevent that. Where real duplicates come from, and how to find one with no index.

• TypeError (fetch failed)

  Node's generic wrapper for a request that got no response. If the same process worked minutes ago, your proxy and certificates are exonerated — look lower.

• 503 upstream connect error or disconnect/reset before headers. reset reason: remote connection failure, transport failure reason: delayed connect error: Connection refused

  A proxy tried a backend and was actively refused. Why that rarely means the vendor is down, why retrying is safe here, and what "before headers" guarantees.

• stream error: stream disconnected before completion: stream closed before response.complete; retrying

  The stream ended with no completion event and no error event. Why there is nothing to recover, why the client's own retry can duplicate work, and when to care.

• AxiosError: Request failed with status code 401

  A 401 with no error body and no request id. Why axios names the caller rather than your Claude credential, and how to find which host refused you first.

• Error: API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.156: Did not find 1 `tool_result` block(s) at the beginning of this message. Messages following `tool_use` blocks must begin with a matching number of `tool_result` blocks."}}

  The index is a pointer into the array you sent, and the cause is ordering as often as it is a missing result. Why the validator only ever names the first break.

• [ERROR] You did not use a tool in your previous response! Please retry with a tool use

  Your agent harness wrote this, not the provider. Why a model answers in prose, why the reminder is self-reinforcing once it is in the history, and what to change.

• exceeded retry limit, last status: 429 Too Many Requests

  Your client's retry policy gave up and kept the least useful field. Why raising the retry limit makes it worse, and which 429 could never have succeeded.

• HTTP 400 Bad Request: {"error":"invalid_redirect_uri"}

  The callback address your client sent is not on the provider's registered list. Where it fails decides whether you can fix it at all, or must ask the app owner.

• invalid_api_key Incorrect API key provided: undefined. You can find your API key at https://platform.openai.com/account/api-keys

  The word undefined is not a wrong key but a missing variable stringified and sent. Why the request still reached OpenAI, and why a rebuild often beats a restart.

• maxTokens (4096) is too close to contextLength (4096)

  A client-side guard, not an API rejection: the output reservation leaves no room for input. Why both numbers are often defaults your tool guessed, not real limits.

• Route Error (400 ): { "error": { "message": "No eligible ChatGPT workspaces found.", "type": "invalid_request_error", "param": null, "code": "chatgpt_account_missing" } }

  A 400 that is not about your request: your signed-in ChatGPT account has no workspace entitled to this product. Who can change that, and why re-signing-in matters.

• The model's tool call could not be parsed (retry also failed)

  The parenthetical is the diagnosis: a second attempt on nearly identical input failed the same way. What stayed constant between the two, and what to change first.

• 429 {"type":"error","error":{"type":"rate_limit_error","message":"Number of request tokens has exceeded your per-minute rate limit (https://docs.anthropic.com/en/api/rate-limits); see the response headers for current usage. Please reduce the prompt length or the maximum tokens requested, or try again later. You may also contact sales at https://www.anthropic.com/contact-sales to discuss your options for a rate limit increase."}}

  A 429 on input tokens, not output. Why a request that fits the context window can still be impossible at your tier, and which header actually tells you the truth.