Error Message Catalog

This chapter covers what went wrong and how to recover when you hit an error message while using Claude Code. For installation and login errors (command not found, PATH, OAuth login failures, etc.), see the Level 1 installation chapter; for troubles with model collaboration behavior patterns, see Level 3 troubleshooting.

tip

For the exact error taxonomy and the latest fixes, the official error reference is the base. This chapter distills the cases readers run into most often.

Automatic Retries Happen First

Server errors, 529 overloads, request timeouts, transient 429 throttles, dropped connections — for all of these, Claude Code automatically retries up to 10 times with exponential backoff before showing an error. The Retrying in Ns · attempt x/y countdown on screen is that in action.

An error appearing on screen = the automatic retries have already been exhausted. Two environment variables tune the behavior:

Variable	Default	Effect
CLAUDE_CODE_MAX_RETRIES	10	Retry count. Lower it in scripts so failures surface quickly. Raise it to ride out long incidents
API_TIMEOUT_MS	600000	Per-request timeout (ms). Raise it on slow networks or behind proxies

Server Errors — Transient Outages

API Error: 500 Internal server error
API Error: Repeated 529 Overloaded errors
Request timed out

The case where things still fail even after automatic retries. Not a problem with your prompt, settings, or account.

Fixes:

• Check status.claude.com for active incidents
• Try again shortly — your previous message stays in the conversation, so for long prompts just typing try again is enough
• If only one model is under heavy load, switch models with /model (capacity is tracked per model)

Usage Limits — Your Plan Is Tapped Out

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm

Your subscription plan's rolling usage limit is exhausted. You're blocked until the displayed reset time.

Fixes:

• Wait for the reset time
• Check plan limits and reset times with /usage
• Pro and Max can buy extra usage with /usage-credits. Team and Enterprise should ask their admin
• To see limits coming before you hit them, add the rate_limits field to a custom statusline (see Velog journal #50 on statusline)

Authentication — Credential Problems

A Stale Environment Variable Overriding Your Subscription

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials

The most common trap. An ANTHROPIC_API_KEY set at a previous job or project is still in your shell profile, and that key belongs to a deactivated organization. The environment variable takes precedence over /login subscriptions, so the stale key gets used first even if you have a Pro or Max subscription.

Fix:

unset ANTHROPIC_API_KEY
claude

Permanently remove the export ANTHROPIC_API_KEY=... line from ~/.zshrc, ~/.bashrc, and ~/.profile. On Windows, check the PowerShell profile ($PROFILE) and user environment variables. Afterwards, confirm the currently active credentials with /status.

Expired Login

OAuth token revoked · Please run /login
OAuth token has expired · Please run /login

Re-authenticate with /login. If it recurs, run /logout first → /login. An inaccurate system clock makes token validation fail, so check your clock.

Network — Cannot Connect

Unable to connect to API. Check your internet connection
fetch failed
SSL certificate verification failed

Corporate proxies, VPNs, and firewalls are the usual causes.

Fixes:

• In the same shell, try curl -I https://api.anthropic.com (on Windows PowerShell use curl.exe — avoid the Invoke-WebRequest alias)
• Behind a corporate proxy, set HTTPS_PROXY before starting Claude Code
• If routing through an LLM gateway, set ANTHROPIC_BASE_URL
• If a corporate proxy intercepts TLS, point to your company's CA bundle with the NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem environment variable. Never use NODE_TLS_REJECT_UNAUTHORIZED=0 (it turns off certificate verification entirely)

Request Errors — Prompt Too Long or Broken State

The Prompt Exceeds the Context Window

Prompt is too long

Fixes:

• Summarize earlier turns with /compact → free up space. Or start fresh with /clear
• Check how much the system prompt, memory, MCP tools, and messages each occupy with /context (see Velog journal #38)
• Remove tool definitions of unused MCP servers with /mcp disable <name>
• Split a giant CLAUDE.md using path-specific rules so parts load only when needed

/compact Itself Fails

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

The case where /compact doesn't even have room to produce a summary. Press Esc twice to go back a few turns, drop some recent messages, then run /compact again. If that still fails, start a new session with /clear → the previous conversation can be restored with /resume.

Image/PDF Size Exceeded

Image was too large. Double press esc to go back and try again with a smaller image.
PDF too large (max 100 pages, 32 MB).

When this error occurs, the image stays in the conversation history and blocks subsequent messages with the same error. Press Esc twice to go back before that turn and re-attach a smaller image. Single images: longest edge up to 8000px; multiple images: 2000px or less.

Tool-Call Flow Gets Tangled

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

The case where a tool call was interrupted mid-way and the history lost consistency. Use /rewind or Esc twice to rewind to just before a checkpoint, then continue. (For checkpoints, see Level 2 checkpointing.)

Response Quality Suddenly Dropped

No errors, but the answers are weaker than usual. The model does not silently change — the cause is almost always conversation state.

Check in this order:

• /model — confirm it's the model you intended. A previous /model selection or the ANTHROPIC_MODEL environment variable may have pinned you to a smaller model
• /effort — check the current reasoning level. Raise it for hard debugging or design work. Defaults differ by model, so don't assume it's at maximum (see Velog journal #44)
• /context — check how full the window is. If it's full, /compact or /clear
• /doctor — detects a bloated CLAUDE.md or subagent definitions

On a turn where the response went wrong, rewind with /rewind rather than correcting via follow-up messages, then retry with a more specific prompt. In-thread corrections leave the failed attempt in context, pulling later answers in that direction too.

Auto Mode — The Classifier Failed to Decide

<model> is temporarily unavailable, so auto mode cannot determine the safety of ...
Auto mode could not evaluate this action and is blocking it for safety
Auto mode classifier transcript exceeded context window

Auto Mode (see Velog journal #43) could not make an auto-approval decision. Reads, searches, and edits inside the working directory skip the classifier, so those keep working.

Fixes:

• First two messages = retry shortly; Claude sees the same message and usually retries automatically
• Third message = in an interactive session it usually falls back to a permission prompt. In non-interactive mode (-p) it aborts — shrink with /compact

Diagnostics and Reporting

For errors not on this page, or when the fixes above don't work:

• /feedback — run inside Claude Code. Sends the transcript and a description to Anthropic and offers a prefilled GitHub issue. With third-party providers like Bedrock, Vertex, or Foundry, it saves a local archive instead
• /doctor — automatically diagnoses local configuration problems
• status.claude.com — check active incidents
• GitHub issues — search existing reports

Summary

Category	First action
Server errors (5xx, 529, timeout)	status.claude.com → retry shortly → switch with /model
Usage limits	Check /usage → wait for reset or /usage-credits
Authentication (stale env)	unset ANTHROPIC_API_KEY → remove from shell profile permanently → confirm with /status
Network	curl -I https://api.anthropic.com → proxy settings, CA bundle
Prompt length	/compact → if that fails, Esc twice → /clear
Tangled tool flow	/rewind
Response quality drop	/model → /effort → /context → /rewind then retry
Auto Mode failure	Retry shortly → fall back to permission prompt → /compact if needed

---

Next level: Level 3 — Intermediate