Table of Contents
- 1. The "diagnostic commands" to run first
- 2. Auth & login
- 3. Usage & rate limits (most common)
- 4. Context & tokens
- 5. Server & model
- 6. Install, PATH & update
- 7. Network & proxy
- 8. MCP (connected servers)
- 9. Permissions & tools
- 10. Other (thinking / image-PDF / IDE)
- 11. Error → fix cheat sheet
- Summary
- FAQ
You're working in Claude Code and it suddenly stops with an error — "log in again," "rate limit," "prompt is too long," "MCP won't connect." There are so many kinds that googling each one gets tedious. This article is a practical reference that catalogs the errors you'll commonly hit in Claude Code, with the cause and the command to run for each.
The bottom line first: for most errors, running claude doctor (full diagnostics), /status (your current auth), and /context (context breakdown) first will narrow down the cause. And the common ones cluster into four families: ① usage/rate limits, ② context overflow, ③ expired auth, ④ MCP connection failures. Below, each category is organized as "symptom → cause → fix command." Bookmark it and jump to the relevant section when you're stuck.
When in doubt, these 3 commands
— most errors start with isolating the cause
The four families: ① usage/rate limits ② context overflow ③ expired auth ④ MCP connection failure.
And quietly, "update to the latest" claude update resolves a lot of bugs.
* The commands and fixes here are based on the official Claude Code documentation (as of 2026). Claude Code updates fast, and command names and message wording can change. Confirm the latest with claude doctor and the official docs.
1. The "diagnostic commands" to run first
Before diving into specific errors, knowing the diagnostic commands that help isolate the cause lets you pin down most problems quickly.
| Command | What it shows / does |
|---|---|
claude doctor | Full check of installation, settings, MCP servers, context usage |
/status | The currently active auth method (Pro / Max / Team / API key) |
/context | Context breakdown (system prompt, history, files, MCP tools) |
/usage | Current plan limits and reset times |
/permissions | List of permission rules (allow/deny) and their sources |
/mcp | MCP server connection status and exposed tool count |
/feedback | Report a bug to Anthropic with the conversation log |
2. Auth & login
The "it was working and suddenly asks me to log in" family. The classic trap is an environment-variable API key overriding your subscription.
| Symptom | Cause | Fix |
|---|---|---|
| Not logged in · Please run /login | No credential available for this session (a saved login that could not be renewed shows Login expired · Please run /login instead) | /login. If it repeats, check system clock and Keychain lock |
| Invalid API key · Fix external API key | The API rejected a key from ANTHROPIC_API_KEY or apiKeyHelper (often a stale key) | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked · Please run /login Please run /login · API Error: 401 OAuth token has expired ... | Signed out everywhere / an admin removed access (revoked); auto-refresh failed (expired) | /login. If it returns in the same session, /logout → /login. If it happens at every launch, suspect clock skew |
| Your ANTHROPIC_API_KEY belongs to a disabled organization · … API Error: 400 ... This organization has been disabled. | A stale ANTHROPIC_API_KEY from a disabled org is in use. If no env var is set, the org behind your /login is the disabled one | Remove the key from shell profile (.zshrc etc.) → /login → confirm with /status. With no env var set, contact support or sign in with a different account |
| 403 Forbidden (after login) | Expired sub / missing role / proxy interference | Check subscription and Console role. For proxies, set HTTPS_PROXY |
Rule of thumb: an environment-variable API key takes precedence over subscription login. If you set ANTHROPIC_API_KEY for a CI job and forgot it, your personal Pro/Max plan gets ignored. Checking "which credential is active" with /status first is the right move. For a deep dive on auth/login fixes (the ANTHROPIC_API_KEY override, token expiry, Keychain and more), see the causes and fixes for login and authentication errors.
3. Usage & rate limits (most common)
The most common complaint with Claude Code. According to the official cost guide (Manage costs effectively), each Claude Code turn carries file contents, tool calls, and multi-step reasoning, so one debugging session can consume more than a day of chat. That is why you hit limits faster than it feels like you should.
3 moves when you "hit the limit"
/usage for limits and reset time, /status for the credential/model for a lighter model, /compact to shrink history, disable unused MCP
Note: "Server is temporarily limiting requests" is a short-lived server-side throttle, not your plan limit. Just wait and retry.
Don't confuse it with plan limits (session/weekly).
More: "API Error: Request rejected (429)" means you hit the rate limit set for your API key (or your Amazon Bedrock / Google Cloud project); if you meant to use a subscription, check /status for a stray ANTHROPIC_API_KEY. "Credit balance is too low" means the Console prepaid balance ran out, or requests are going out on a Console API key when you meant to use your subscription (top up, or check the key in /status and remove it). Note that in March 2026, Pro and Max users complained that their Claude Code limits were running out far faster than expected, and Anthropic acknowledged it was investigating as a top priority (The Register, March 31, 2026). If it recurs, update to the latest version, measure with /usage, and file /feedback if needed. For systematic token-saving, see AI token-saving and Claude Code token saving. For how "usage limit reached" works (the 5-hour window and the weekly window) and what to do once you hit the cap, see the dedicated guide on usage limit reached.
4. Context & tokens
This shows up when you handle long meetings or huge files.
| Symptom | Cause | Fix |
|---|---|---|
| Prompt is too long | Conversation + files exceed the context window | /compact (summarize), /clear (reset), /context to see the breakdown, disable unused MCP via /mcp |
| Error during compaction: Conversation too long | Not enough free space for the compaction output | Esc twice to rewind a few turns, then /compact. If still stuck, /clear |
| Autocompact is thrashing | A huge output refills context right after compaction | Read big files by line range / /compact keep only <focus> / move to a subagent |
The trick is to never read a huge file whole. Pass logs and data in small line-range chunks. Grasping the context window idea makes this class of error far rarer. For the detailed causes and fixes of the Prompt is too long error (the 200K vs 1M window, using subagents), see the dedicated article.
5. Server & model
| Symptom | Cause | Fix |
|---|---|---|
| 500 Internal server error | Temporary Anthropic-side failure | Check status.claude.com → retry after 1 min |
| 529 Overloaded (repeated) | API at capacity temporarily | Wait a few minutes. Switch model with /model to spread load |
| Request timed out | No response within the 10-min default | Split the task. On a slow line, raise API_TIMEOUT_MS |
| There's an issue with the selected model / Model '…' not found | Wrong model name or not in your plan | /model to reselect. Check stale ANTHROPIC_MODEL env var |
| Claude Opus is not available with the Claude Pro plan | Selected model not in your plan | /model to an available one. After a plan change, /logout→/login |
For why 529 Overloaded / 500 are server-side and don't consume your quota, how auto-retry (up to 10x) works, and how it differs from 429, see 529 Overloaded / 500: causes and fixes.
6. Install, PATH & update
| Symptom | Cause | Fix |
|---|---|---|
| command not found: claude | Install dir not on PATH | Add ~/.local/bin (Win: %USERPROFILE%\.local\bin) to PATH |
| Install fails (HTML error, etc.) | Proxy / region block | Homebrew brew install --cask claude-code / WinGet winget install Anthropic.ClaudeCode |
| TLS / SSL certificate verification failed | Corporate proxy TLS inspection / missing CA | Point NODE_EXTRA_CA_CERTS=/path/ca.pem. NEVER set NODE_TLS_REJECT_UNAUTHORIZED=0 |
| Multiple Claude Code installations (version mismatches, unexpected behavior) | Duplicates among native, npm, Homebrew, WinGet, etc. | Check with which -a claude (Windows: where.exe claude) and keep one; the native install at ~/.local/bin/claude is recommended. E.g. npm uninstall -g @anthropic-ai/claude-code |
| Bugs from an old version | Not updated | claude update (the top fix that resolves many bugs) |
| Desktop app says "Can't open this app" | The MSIX package was half-registered during an update (Windows) | End the background processes, then Repair in Settings. Full write-up |
For the causes and fixes of command not found: claude (PATH, multiple-install conflicts, npm permissions, the Windows wrong-shell trap), see how to fix the "command not found" install/PATH error.
7. Network & proxy
Common on corporate networks and VPNs. First confirm reachability with curl -I https://api.anthropic.com.
| Symptom | Cause | Fix |
|---|---|---|
| Unable to connect to API / Connection refused … (ECONNREFUSED) | Offline / VPN block / proxy not set | Set HTTPS_PROXY=http://proxy:8080. Ask IT to allow api.anthropic.com |
| SSL certificate verification failed (corporate) | Self-signed interception cert | Get the CA bundle from IT and set NODE_EXTRA_CA_CERTS |
| 403 host_not_allowed (cloud runs) | Outside the cloud env allowlist | Set network access to Custom and allow the target domain |
| Connection lost mid-response (before v2.1.227: Connection closed mid-response) | It connected and streaming had started, then the connection was severed | The partial output is kept, so reply continue. If it repeats, check claude --version and update |
For a deeper dive on proxy setup, TLS certificates (NODE_EXTRA_CA_CERTS), allowlist domains, and why NODE_TLS_REJECT_UNAUTHORIZED=0 is dangerous, see connection and proxy error causes and fixes. Connection lost mid-response (formerly Connection closed mid-response) is a different problem that happens after the request arrives — causes and fixes when the response is cut off mid-way covers the isolation steps and which versions fixed what.
8. MCP (connected servers)
You hit these once you start using MCP servers. Check status first with /mcp.
| Symptom | Cause | Fix |
|---|---|---|
| Server failed to connect / Pending approval | Server crashed / unreachable / auth needed | /mcp for status. stdio: check command exists + executable; HTTP: check URL/auth headers |
| Tool not found | Connected but no tools exposed / wrong name | /mcp to confirm tool count, claude mcp get <name> for health |
| Reconnection attempts exhausted | HTTP/SSE server down after 5 retries | Confirm the server is up, manual reconnect in /mcp. For stdio, restart claude |
| MCP server timeout | Startup does not finish within MCP_TIMEOUT (default 30 s) | Raise it in ms, e.g. MCP_TIMEOUT=60000 claude. The "timeout" in .mcp.json is a per-tool execution limit, not the startup wait |
For status-by-status fixes when an MCP connection is failed, needs authentication, or pending (including wrapping npx with cmd /c on Windows), see how to fix MCP connection errors.
9. Permissions & tools
The "asked for permission even in bypass mode" family. Two key points: the official docs list the actions that still prompt in bypass mode, and deny rules block in every mode, including bypass (allow rules have no effect in bypass; see the official Choose a permission mode).
| Symptom | Cause | Fix |
|---|---|---|
| Asked for permission even in bypass mode | Explicit ask rules, tools that need user interaction such as AskUserQuestion, and rm / rmdir on a critical path such as the root, your home, or the working directory (what the docs call a circuit breaker) still prompt in bypass. Writes to protected paths such as .git and .claude do not prompt in bypass | Check and adjust ask rules in /permissions. Deny rules block without prompting |
| Tool execution denied by PreToolUse hook | A hook blocked it with exit code 2 | Check the hook in .claude/settings.json. See output with claude --debug |
For why bypass still stops, see why it asks for permission even in bypass mode; for safe permission design, see permission modes and security.
10. Other (thinking / image-PDF / IDE)
- thinking blocks cannot be modified (400): a known bug where extended-thinking blocks get corrupted in history. Esc twice → /rewind, else a new session, and
claude update. Details: thinking blocks 400 error. - court / a raw <invoke> tag is shown and the tool never runs: a known bug where the tool-call control tag is generated broken. If it fails twice, start a fresh session (/clear). Details: court / invoke tag leak error explained.
- Could not check the pull request status: a GitHub-connection issue (often
ghauth). Start withgh auth status. Details: PR-status error. - Image was too large / PDF too large: images over 8000px on the long edge (2000px when many images are in context), PDFs over 100 pages / 20 MB get rejected. Esc twice to remove the attachment; resize or read by line range. Reference big files by path instead of pasting.
- VS Code extension won't connect: confirm
claude --versionworks in the VS Code terminal. Check PATH, restart VS Code, reinstall the extension.
11. Error → fix cheat sheet
| When this happens | Try this first |
|---|---|
| Cause unknown / general | claude doctor → /status → /context |
| Suddenly asked to log in | /status → (if a stale key) unset ANTHROPIC_API_KEY → /login |
| Hit a rate limit | /usage → /model lighter → /compact → wait |
| Prompt is too long | /compact → /clear → read big files by line range |
| 500/529/timeout | Check status.claude.com → wait a bit → /model |
| command not found: claude | Add ~/.local/bin to PATH |
| Can't connect (corporate NW) | curl -I https://api.anthropic.com → HTTPS_PROXY/NODE_EXTRA_CA_CERTS |
| MCP won't connect | /mcp → check URL/perms/command → MCP_TIMEOUT |
| Prompted even in bypass | /permissions to check ask rules (critical-path removals prompt even in bypass) |
| Just want it fixed | claude update (the latest version fixes a lot) |
Summary
Claude Code has many errors, but the first move is to isolate the cause with three commands: claude doctor / /status / /context — that gets most problems moving again. The common ones are four families — usage/rate limits, context overflow, expired auth, MCP connection failure — with /usage, /compact, /login, and /mcp as the first-line fixes.
And the easily-overlooked strongest move is keeping it current with claude update. Claude Code updates fast, and past bugs (like the thinking-blocks 400) often vanish just by bumping the version. "When stuck, the three diagnostic commands first; if it's not fixed, update to the latest." Keep that pattern, and you'll stop melting time into errors.
If it's not an error but the behavior feeling too heavy or too slow that bothers you, revisiting Claude Code's effort setting lets you tune the balance between reasoning depth and token consumption. Related reading: thinking blocks 400 error, PR-status check error, Claude Code token saving, why it asks for permission in bypass mode, what is MCP, and The model returned no content — Causes and Fixes.
FAQ
Q. An error appeared — what do I do first?
A. Run claude doctor. It checks installation, settings, MCP, and context in one go. Then look at /status (current auth) and /context (what's eating context), and you can usually tell whether it's an auth, context, or connection issue.
Q. I hit rate limits quickly. What helps?
A. Each Claude Code turn carries file contents and tool calls, and the official docs note that one debugging session can consume more than a day of chat, so you hit them sooner than expected. Check limits and reset time with /usage, switch to a lighter model with /model, shrink history with /compact, and disable unused MCP. If that's not enough, consider a higher plan (Max, etc.) or extra credits.
Q. It says "Invalid API key" but my key should be correct.
A. The classic cause is a stale ANTHROPIC_API_KEY environment variable overriding your subscription. Check with env | grep ANTHROPIC, unset ANTHROPIC_API_KEY (remove it from your shell profile too), then /login and confirm with /status.
Q. It won't connect on my corporate network.
A. First confirm reachability with curl -I https://api.anthropic.com. For a proxy, set HTTPS_PROXY; for TLS inspection, point NODE_EXTRA_CA_CERTS at the CA cert. Don't use NODE_TLS_REJECT_UNAUTHORIZED=0 — it's dangerous. The proper route is asking IT to allow api.anthropic.com.
Q. Nothing I try works — last resort?
A. Update to the latest with claude update. Claude Code updates fast and known bugs often disappear just by bumping the version. If it still fails, file it with /feedback (includes the conversation log) to Anthropic.
