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 valid credential (expired token, etc.) | /login. If it repeats, check system clock and Keychain lock |
| Invalid API key | A stale ANTHROPIC_API_KEY remains | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked / expired | Logged out elsewhere / admin disabled | /logout → /login. Suspect a clock skew too |
| This organization has been disabled | API key from a disabled org overrides | Remove the key from shell profile (.zshrc etc.) → /login → confirm with /status |
| 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.
3. Usage & rate limits (most common)
The most common complaint with Claude Code. Claude Code consumes 10-100x the tokens of chat (multi-turn conversations, huge contexts, tool round-trips), so 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: "429 / Request rejected" is a rate overrun on your API key or workspace. "Credit balance is too low" is depleted Console prepaid balance (top up in billing or switch to a subscription). Note that around March 2026, Max users reported their 5-hour windows draining unusually fast in tech media and the official repo's issues (suspected bug). 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.
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 |
| Auto-compact 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.
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 |
| model not found / no access | Wrong model name or not in your plan | /model to reselect. Check stale ANTHROPIC_MODEL env var |
| Opus is not available with Pro plan | Selected model not in your plan | /model to an available one. After a plan change, /logout→/login |
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 installations found | npm/Homebrew/native duplicates | Keep one, 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) |
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 / ECONNREFUSED / ETIMEDOUT | 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 |
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 >5s, etc. | MCP_TIMEOUT=10000 claude (ms). Per-server: "timeout" in .mcp.json |
9. Permissions & tools
The "asked for permission even in bypass mode" family. The key point: deny rules take precedence over allow and bypass.
| Symptom | Cause | Fix |
|---|---|---|
| Asked for permission even in bypass mode | Deny rules win; dangerous ops always prompt (circuit breaker) | Check and adjust deny rules in /permissions |
| 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. - 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, PDFs over 100 pages / 32 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 deny rules |
| 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.
Related reading: thinking blocks 400 error, PR-status check error, Claude Code token saving, why it asks for permission in bypass mode, and what is MCP.
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. Claude Code consumes 10-100x the tokens 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.
