Vadym Samoilenko 5f3f21a8c5 vault backup: 2026-04-17 12:44:18

2026-04-17 12:44:18 +01:00

8.6 KiB

Raw Permalink Blame History

title

aliases

Claude Code Error Reference

Runtime errors Claude Code displays during operation. All three surfaces (CLI, Desktop app, Web) share the same error set since they wrap the same CLI. Errors shown here mean retries (up to 10, exponential backoff) have already been exhausted.

Retry Behavior

Claude Code retries automatically before surfacing any error. Spinner shows Retrying in Ns · attempt x/y.

Env Var	Default	Effect
`CLAUDE_CODE_MAX_RETRIES`	10	Retry attempts
`API_TIMEOUT_MS`	600000 (10 min)	Per-request timeout in ms

Server Errors

Originate in Anthropic infrastructure — not your account or request.

500 Internal Server Error

Cause: Unexpected API failure, unrelated to your prompt
Fix: Check status.claude.com, wait a minute, type try again. Run /feedback if it persists.

529 Overloaded

API Error: Repeated 529 Overloaded errors

Cause: API at capacity across all users; does NOT count against your quota
Fix: Wait a few minutes; run /model to switch models (capacity tracked per model)

Request Timed Out

Cause: High load or very large response; default timeout is 10 min
Fix: Retry; break large tasks into smaller prompts; raise API_TIMEOUT_MS for slow networks

Auto Mode Safety Classifier Unavailable

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool>

Cause: Classifier model overloaded; reads/searches/edits in working directory still work
Fix: Retry after a few seconds; transient, no settings change needed

Usage Limits

Tied to your account/plan quota, distinct from server errors.

Session / Weekly / Model Limit

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

Fix: Wait for reset; run /usage to check limits; /extra-usage to buy more on Pro/Max; monitor with rate_limits in wiki/claude-code/overview or Desktop usage ring

429 Rate Limit

API Error: Request rejected (429)

Cause: Rate limit on your API key, Bedrock project, or Vertex AI project
Fix: Run /status — a stale ANTHROPIC_API_KEY may be routing to a low-tier key; lower CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY; reduce parallel subagents

Credit Balance Too Low

Fix: Add credits at platform.claude.com/settings/billing; enable auto-reload; set per-workspace spend caps

Authentication Errors

Run /status to see which credential is active.

Error	Cause	Fix
`Not logged in`	No valid credential	`/login` or set `ANTHROPIC_API_KEY`
`Invalid API key`	Key rejected	Check Console for revocation; run `env \| grep ANTHROPIC` to find stale `.env` keys
`Organization has been disabled`	Disabled org key overrides subscription	Unset `ANTHROPIC_API_KEY`, relaunch
`OAuth token revoked/expired`	Session token invalid	`/logout` then `/login`
`OAuth scope: user:profile`	Token predates new scope	`/login` to mint fresh token

Auth precedence: ANTHROPIC_API_KEY env var overrides /login subscription, even in non-interactive mode (-p).

Network Errors

Almost always local: VPN, proxy, or firewall — not Anthropic infrastructure.

Unable to Connect

Unable to connect to API (ECONNREFUSED / ECONNRESET / ETIMEDOUT)

Diagnose: curl -I https://api.anthropic.com from same shell
Fix: Set HTTPS_PROXY; set ANTHROPIC_BASE_URL for LLM gateways; allow api.anthropic.com in firewall
WSL: Check /etc/resolv.conf for broken nameserver
macOS: Stale VPN tunnel interfaces (ifconfig → remove utun); Docker Desktop can intercept traffic

SSL Certificate Errors

SSL certificate verification failed
Self-signed certificate detected

Cause: Corporate proxy doing TLS inspection; Node.js doesn't trust its cert
Fix: NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem — do NOT use NODE_TLS_REJECT_UNAUTHORIZED=0

Request Errors

API received the request but rejected its content.

Context Window Full

Prompt is too long

Fix: /compact to summarize; /clear to start fresh; /context to inspect usage; disable unused MCP servers with /mcp disable <name>; trim CLAUDE.md files
Note: Auto-compact is on by default; re-enable if DISABLE_AUTO_COMPACT was set
Subagents: Inherit all parent MCP tool definitions — disable unused MCP before spawning

Compaction Failed

Error during compaction: Conversation too long

Fix: Press Esc twice → step back several turns → run /compact again; or /clear + /resume

Request Too Large (30 MB HTTP limit)

Fix: Press Esc twice; reference large files by path instead of pasting

Image Too Large

Fix: Press Esc twice; max 8000px longest edge (single image), 2000px when many images in context; take tighter screenshots

PDF Errors

Too large (>100 pages / 32 MB): use Read tool with page range or pdftotext
Password protected: remove protection first
Invalid: re-export from source

Extra Inputs Not Permitted (400)

API Error: 400 ... Extra inputs are not permitted ... context_management

Cause: LLM gateway strips anthropic-beta header but forwards body with beta-only fields
Fix: Configure gateway to forward anthropic-beta; or set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

Model Not Found / No Access

Fix: Run /model to pick from available models; use aliases (sonnet, opus) instead of versioned IDs to avoid staleness

Opus Not Available on Pro Plan

Fix: /model to select an included model; if recently upgraded, /logout then /login to refresh token

`thinking.type.enabled` Not Supported

Cause: Claude Code version < v2.1.111 on Opus 4.7
Fix: claude update to v2.1.111+; or switch to Opus 4.6 / Sonnet

Thinking Budget Exceeds Output Limit

max_tokens must be greater than thinking.budget_tokens

Cause: Common on Bedrock/Vertex when MAX_THINKING_TOKENS > provider output limit
Fix: Lower MAX_THINKING_TOKENS or raise CLAUDE_CODE_MAX_OUTPUT_TOKENS

Tool Use / Thinking Block Mismatch (400)

API Error: 400 due to tool use concurrency issues

Cause: Conversation history corrupted (interrupted tool call or mid-stream edit)
Fix: /rewind or Esc × 2 to step back to a clean checkpoint

Response Quality Seems Off (No Error)

Claude Code never silently downgrades models. Check:

/model — confirm expected model; ANTHROPIC_MODEL env var may override
/effort — check reasoning level; raise for hard tasks (ultrathink)
/context — check window fill level; /compact or /clear if near capacity
/doctor — flags oversized CLAUDE.md files and subagent definitions
Rewind, don't correct — press Esc × 2 or /rewind before the bad turn; replying keeps the wrong answer in context

Reporting

/feedback — sends transcript + description to Anthropic (unavailable on Bedrock/Vertex/Foundry)
/doctor — local config check
status.claude.com — active incidents
GitHub issues: anthropics/claude-code

Key Takeaways

Retries are automatic — when you see an error, 10 retries with backoff have already run
529 ≠ your quota — overloaded errors don't count against usage limits
ANTHROPIC_API_KEY wins — an env var key always overrides /login subscription, including disabled-org keys hiding in .env files
Gateway proxy issues surface as Extra inputs not permitted when anthropic-beta header is stripped
Context errors: /compact → Esc×2 to step back → /compact again → /clear as last resort
Image errors persist until you Esc×2 past the turn that added the image
Quality issues: check /model, /effort, /context before assuming model regression; prefer /rewind over in-thread correction

wiki/claude-code/overview — full product capabilities, all surfaces
wiki/claude-code/mcp-integration — MCP server errors and /mcp disable usage
wiki/claude-code/custom-subagents — context inheritance issues when spawning subagents

Sources

raw/Error reference.md — scraped from code.claude.com/docs/en/errors

8.6 KiB Raw Permalink Blame History Unescape Escape