Troubleshooting and FAQ
📚 Series Navigation: The previous article 50 Anti-Patterns: Common Misuse Cases highlighted intuitive but counter-productive habits. This article continues with troubleshooting—how to isolate and resolve tool failures when Claude Code malfunctions. From installation errors and login locks to permissions, disconnected MCPs, performance lag, and API error codes, this guide maps symptoms to actionable diagnostics. The next article is 52 Glossary.
Let's start with a typical, easily-encountered troubleshooting scenario to show what this guide addresses.
Imagine this: you configure Claude Code on a new Mac, and upon launching, it throws This organization has been disabled. You suspect account termination, quickly log into claude.ai to verify subscriptions—the account profile is active. You assume proxy failure, modify routing rules, and restart—with no change. After spending forty minutes reinstalling dependencies and preparing support tickets, you check configurations.
The root cause: the system migration from your previous machine imported ~/.zshrc, containing a forgotten export ANTHROPIC_API_KEY=... from an inactive project. The environment variable took priority over your subscription login profile. Claude Code authenticated using the invalid API key, triggering the error page. Running unset ANTHROPIC_API_KEY resolved the issue.
The takeaway: never troubleshoot by guessing. Those forty minutes were wasted on assumptions about accounts or networks. Claude Code provides built-in tools; running /status displays active credentials immediately, resolving assumptions. This article shows you how to isolate problems systematically.
After reading this article, you will get:
- A symptom-to-resolution routing table to classify errors before trying fixes
- How and when to use the primary diagnostic commands:
/doctorand/feedback - Actionable resolutions organized into six categories: installation, logins, permissions, MCP, performance, and API errors
- How to leverage
--debuglogs and "clean context comparisons" to isolate variables - A hands-on guide running
/doctorto audit your local environment
01 The First Rule: Classify Before Repairing
The primary principle: when encountering an error, classify it first—is it an installation issue, login block, configuration conflict, or remote API outage? Misclassifying the category leads to wasted troubleshooting cycles.
Analogy: Plumbing leak diagnostics. A plumber doesn't tear up flooring at the first sign of water—they isolate the leak (faucet seals, joint threads, or ceiling runoffs) first. Misdiagnosing the source leads to unnecessary destruction. Troubleshoot Claude Code similarly: triage before repairing.
This is important because Claude Code's documentation is divided into distinct categories—installation, login blocks, runtime errors, configuration, and performance. Identifying the category guides you to the correct resource page. The official troubleshooting guide outlines this routing table:
| Symptom | Category / Chapter Reference |
|---|---|
command not found: claude, installation errors, PATH blocks, EACCES warnings | Installation (Chapter 02 & Section 02) |
Repetitive login prompts, 403 Forbidden checks, organization disabled pages | Authentication (Section 03) |
| Settings ignored, hook triggers failing, MCP configs unread, rules bypassed | Configuration (Section 04) |
API Error: 5xx, 529 Overloaded capacities, 429 limits | API Errors (Section 06, typically remote outage) |
model not found or you may not have access to it | Model Access (Section 06, version selection errors) |
| Console lag, high CPU/RAM memory, file search failures | Performance (Section 05) |
Keep this official instruction in mind: "If you are unsure which applies, run /doctor within Claude Code to automatically check your installation, settings, MCP servers, and context usage. If claude won't start at all, run claude doctor from your shell."
If the category is unclear, run /doctor first to locate the issue. The next section details these commands.
💡 Summary in one sentence: Isolate before repairing—classify the symptom using the routing table, running
/doctor(orclaude doctor) if the category remains unclear.
02 Two Diagnostics Commands: /doctor and /feedback
Claude Code features two built-in diagnostics commands. Most environment issues are surfaced by /doctor; unresolved platform bugs can be reported via /feedback. Mastering them saves debugging time.
Analogy: A general checkup. Medical diagnostics require exams (blood pressure, heart rates, lab values) before starting treatment. /doctor is the scan utility for Claude Code: it audits installation scripts, settings syntax, MCP connection statuses, and active context sizes in a single pass.
/doctor: Environment Audit
Run /doctor first. It inspects: installation scripts, config key validation (checking for invalid parameters or schema errors), active MCP servers, and context sizes.
Choose the command based on execution status:
- Session active: run
/doctordirectly in the prompt. - CLI won't start (e.g.,
command not foundor crash on run): executeclaude doctorin your host shell—without the slash.
A useful feature: if /doctor reports failures, press f to stream the audit report back to Claude, letting the agent assist in resolving the errors.
/feedback: Submit Issues
If the issue persists after reviewing manuals and running /doctor, use /feedback to report it to Anthropic. This uploads logs and prompts, providing a direct channel for debugging complex issues (such as quality degradation without explicit error codes). It includes an option to open a pre-populated GitHub issue. Note: if you access via Bedrock or Vertex, /feedback caches logs locally instead of transmitting to Anthropic, requiring you to forward them to your enterprise account representatives.
You might encounter references to
/bug—this is the obsolete name for feedback. The current standard is/feedback: sending reports directly or opening pre-populated GitHub issues.
| Situation | Target Command | Purpose |
|---|---|---|
| Uncertain error category | /doctor | Performs environment diagnostics |
| CLI fails on startup | claude doctor (in shell) | Pre-start validation check |
| doctor reports errors; let Claude resolve | Press f in diagnostic outputs | Streams reports to prompt history |
| Unresolved after reviewing manuals | /feedback | Transmits session logs to Anthropic |
| Suspecting API outages | Open status.claude.com in browser | Verifies active server status |
Keep status.claude.com in mind: if you receive 5xx or 529 server errors, check the status page first before modifying local configs—the issue is typically remote server load, not local file settings (Section 06).
💡 Summary in one sentence: Triage environments using
/doctor(orclaude doctor) for auto-diagnostics, and/feedbackto report unresolved platform issues; checkstatus.claude.comon suspected API outages.
03 Authentication: Login Prompts and Organization Errors
Authentication issues can throw worrying errors (like disabled, Forbidden, or revoked), but resolutions are usually straightforward.
Analogy: Employee badges failing at gates. An invalid badge prompt doesn't mean your employment was terminated—it could be a demagnetized strip, scanning an obsolete ID card, or system clock drift. Authentication warnings follow similar patterns: inspect what credentials Claude Code is presenting before assuming account suspension.
Step 1: Inspect active credentials
This is the universal baseline diagnostics command. Type:
/statusExpected: Output displays the active authentication profile—e.g., OAuth subscriptions or a specific API key. If you have an active subscription but the output displays an API key, the issue is identified.
The Priority Trap: ANTHROPIC_API_KEY overriding OAuth
This is the scenario covered in our introduction. The official documentation states:
Environment variables take precedence over
/login, so a key exported in your shell profiles or loaded from a.envfile will be used even if you have an active Pro or Max subscription. In non-interactive mode (-p), the key is always used if present.
If an old ANTHROPIC_API_KEY is present in your environment, Claude Code defaults to it. If the key has expired or the organization associated with it is disabled, it throws This organization has been disabled. The fix:
unset ANTHROPIC_API_KEY
claudeAs unset only affects the current terminal session, make it permanent by deleting export ANTHROPIC_API_KEY=... from ~/.zshrc, ~/.bashrc, or ~/.profile (on Windows, check PowerShell configurations $PROFILE and User Environment variables). Restart claude and run /status to verify subscription access. Refer to Chapter 04 for credentials priority rules.
| Error | Root Cause | Resolution |
|---|---|---|
Not logged in · Please run /login | No valid session credentials | Run /login; if using env tokens, check export ANTHROPIC_API_KEY |
OAuth token revoked / has expired | Cached OAuth session has expired | Run /login; run /logout first if it repeats in the same window |
| Repetitive login requests across launches | Token checks consistently fail | Check system clock settings (token verification relies on correct timestamps); on macOS, run claude doctor to audit Keychain permissions |
403 Forbidden (after login) | Subscription, role, or proxy blocks | For Pro/Max, check configurations at claude.ai/settings; for Console keys, verify Claude Code or Developer roles |
Invalid API key | API token rejected | Check token formatting and active Console status; run `env |
The system clock timestamp constraint is a common trap—VM environments offline can drift by days, causing token signature checks to reject authorization instantly. Aligning system times resolves this.
💡 Summary in one sentence: Run
/statusto inspect active credentials first; clear residualANTHROPIC_API_KEYsettings in shell configurations if they override OAuth subscription setups, checking system clocks and OS Keychains on repeated login warnings.
04 Configuration: Ignored Settings, Hooks, and MCP Files
The second category is ignored configurations—defining settings, hook filters, or MCP servers in settings.json that the agent ignores. The debugging rule: check what settings Claude Code loaded in the active session first, rather than assuming configurations are active.
Analogy: Handovers missing delivery confirmation. Placing an edit in a file doesn't guarantee the runtime reads it—it could be mapped in the wrong directory, overridden by configuration hierarchy, or malformed. Verify what was read by the process instead of repeating file edits.
Active Config Diagnostics Commands
| Command | Inspects |
|---|---|
/context | Active context window memory allocation (system prompts, cached files, skills, tools) |
/memory | Active CLAUDE.md and repository guidelines |
/skills | Available skills (user-level, project-level, or plugins) |
/agents | Subagent profiles and configurations |
/hooks | Registered session hooks |
/mcp | MCP server statuses and tool access |
/permissions | Active allow/deny rules |
/debug [issue] | Enables session debug logging and directs Claude to inspect files |
/status | Active configuration profiles (including hosted configurations) |
Run the query matching the ignored parameter. If a hook fails to trigger, run /hooks to verify registration status—if missing, the JSON was not read; if present, the matcher filter query is likely incorrect.
Typical Configuration Traps
Common traps from the troubleshooting logs include:
| Symptom | Root Cause | Resolution |
|---|---|---|
| Hook fails to trigger | Matcher value is lowercase (e.g., "bash") | Tool names are case-sensitive and capitalized: Bash, Edit, Write, Read |
| Hook fails to trigger | Hook is placed in a separate file | Place hooks strictly under the "hooks" key in settings.json |
settings.json parameters ignored | Conflict with settings.local.json | settings.local.json overrides settings.json, overriding user-level files (Chapter 31) |
.mcp.json servers fail to load | File is located in the .claude/ folder | Save .mcp.json in the repository root directory, not in .claude/ |
| Project MCP server missing | One-time approval prompts were skipped | Project-level servers require approval; run /mcp to authorize (Chapter 22) |
Subdirectory CLAUDE.md rules ignored | Loaded on demand | Rules load only when Claude reads files in that directory, not on startup (Chapter 18) |
The case-sensitive tool matcher is a common trap: writing "edit|write" for a PostToolUse hook prevents it from running. The /hooks list shows it active, but matcher rules fail because tool names must be capitalized as "Edit|Write". From the docs: "Matching is case-sensitive."
Run-time & Permissions issues
Permission issues typically fall under config triaging. Two cases are common:
1. Request constraints vs. hard limits. Directives in CLAUDE.md like "never edit .env" are style guidance, not strict execution limits. To enforce hard gates regardless of the agent's intent, use permission rules or hooks (Chapters 20 & 21). To block operations, use deny rules or PreToolUse hooks, not CLAUDE.md guidelines.
2. Matcher string limits. If you write a rule blocking Bash(rm *), the agent can bypass it using /bin/rm or find . -delete. This happens because prefix matching checks literal command strings, not system calls. Add explicit rules for commands or rely on PreToolUse hooks and container sandboxes for hard safety gates. Run /permissions to audit active rules.
💡 Summary in one sentence: Triage ignored settings via
/context,/memory,/hooks,/mcp, or/permissions; typical errors include case mismatches in hook matchers, setting overrides insettings.local.json, mislocated.mcp.jsonfiles, and usingCLAUDE.mdguidelines for security limits.
05 Performance: Lag, Memory Footprints, and Search Issues
Performance issues (slow responses, high memory footprint, or @file search failures) are documented under "Performance and Stability." These are typically caused by context bloat rather than software bugs.
Analogy: Background tasks consuming system RAM. When a computer lags, you close background programs and clear temp files before calling support. Triage Claude Code similarly: clean up context spaces before reinstalling.
Console Lag and Memory Footprint
The official guide lists these interventions:
- Run
/compactregularly (summarizing chat history, Chapter 19). - Restart the CLI between major tasks.
- Exclude build directories in
.gitignoreto prevent file scans.
If RAM usage remains high, run /heapdump—this exports a JavaScript heap capture to your desktop directory to attach to GitHub issues.
Hangs and infinite loaders: press
Ctrl+Cto cancel the active command; if unresponsive, restart the shell window. Restarting does not lose session data; runclaude --resumein the repository directory to restore context.
Auto-compact Thrashing Alerts
If you see Autocompact is thrashing: the context refilled to the limit..., this means compaction succeeded but a massive file read or command output filled the context window immediately again. To prevent API call loops, Claude Code pauses. Resolve this by having the agent read files in line segments, targeting /compact to keep only specs/diffs, or resetting via /clear.
@file Search Failures: Ripgrep configurations
If @file queries fail to locate files, the bundled ripgrep utility is likely failing to execute on your environment. Install a native system build and configure Claude Code to default to it:
brew install ripgrepThen export USE_BUILTIN_RIPGREP=0 in your environment (Chapter 42).
| Symptom | Resolution |
|---|---|
| Lag, memory footprint | Run /compact and restart the CLI |
| CLI hangs | Press Ctrl+C or restart the shell and run claude --resume |
| Auto-compact thrashing warning | Segment file reads and run /compact keep only ... |
@file search failing | Install system ripgrep and export USE_BUILTIN_RIPGREP=0 |
| Console fonts corrupting (block characters) | Run /terminal-setup to disable GPU console acceleration |
Font corruption can occur in VS Code consoles. Running /terminal-setup to disable GPU acceleration and restarting the terminal window resolves it—this is a terminal renderer issue, unrelated to Claude Code.
💡 Summary in one sentence: Triage console lag using
/compactand CLI restarts; resolve hangs usingCtrl+Corclaude --resume; fix search bugs via systemripgrepinstallations; resolve corrupted characters via/terminal-setup.
06 API Errors: Server Issues vs. Input Errors
When the console outputs API Error: ..., determine first if the root cause is a remote outage or local configuration error—since they require different resolutions.
Note: Automatic Retry Cycles
Claude Code includes a retry handler: on server errors, overload alerts, timeouts, or connection failures, it executes exponential backoff retries (up to 10 attempts). The console displays Retrying in Ns · attempt x/y. Seeing a final error log means all retries were exhausted.
Categorizing API Error Logs
We classify typical API errors into three profiles:
| Error Log | Source | Action |
|---|---|---|
API Error: 500 / 529 Overloaded / Server is temporarily limiting requests | Remote Server | Retry later; check status.claude.com; run /model to shift models (quotas are version-scoped) |
You've hit your session/weekly/Opus limit | Account Quota | Wait for reset; run /usage; top up billing via /usage-credits |
Prompt is too long / Request too large | Local Context | Run /compact or /clear; request segmented file reads instead of pasting whole contents |
Resolutions differ: server overloads require waiting or switching models, quota limits require billing top-ups, and context size errors require pruning inputs. Distinguish these categories before writing fixes.
Connection errors (Unable to connect to API, fetch failed, or network timeouts) point to local proxy settings, VPN configurations, or firewalls. Triage this by running curl against the API endpoint in your terminal:
curl -I https://api.anthropic.comIf it resolves, network routes are functional (implying SSL/proxy issues); connection failures point to route blockage. Configure VPN tunnels or export HTTPS_PROXY variables. Adjust timeout thresholds using these environment variables (Chapter 42):
| Environment Variable | Default Value | Purpose |
|---|---|---|
API_TIMEOUT_MS | 600000 (10 minutes) | Request timeout threshold; increase on slow routes |
CLAUDE_CODE_MAX_RETRIES | 10 | Max automatic retry attempts; decrease in scripts to fail early |
Typical Access and Policy Warnings
1. model not found or you may not have access to it. The configured model version is unrecognized or restricted. Run /model in the CLI to select active models. If the error repeats, audit obsolete model IDs across precedence paths: --model CLI flags -> ANTHROPIC_MODEL environment variables -> settings.local.json -> project/user settings.json. Delete overrides to fallback to defaults. Always reference aliases (e.g., sonnet, opus) rather than hardcoded build strings to ensure automatic updates (Chapter 04).
2. Usage Policy violations. Policy filters evaluate the entire conversation history, not just the last prompt. Repeating queries with minor edits within the same session will still trigger blocks. Revert the dialogue using /rewind or double-pressing Esc (Chapter 37) to remove the offending turn, or run /clear to start a clean session.
💡 Summary in one sentence: Triage API warnings into three scopes—server load (
5xx/529), billing limits, and context bloat (too long); resolve route failures via local proxy configurations, and specify model aliases rather than hardcoded IDs.
07 Advanced Debugging: --debug Logs and Sandbox Mode
If standard troubleshooting steps fail, use these two advanced diagnostics methods:
Analogy: Diagnostic meters and circuit isolation. When resolving hardware failures, electricians trace real-time signals with meters and isolate components sequentially. Our advanced methods mimic this approach.
Method 1: CLI --debug Flags
Enable logging on startup using --debug flags to inspect execution steps:
| Command | Used For |
|---|---|
claude --debug | General debugging logs |
claude --debug mcp | MCP server startup/STDERR outputs |
claude --debug hooks | Hook event matcher validation and outputs |
You can also run /debug [issue description] inside an active session to enable debugging logs.
Method 2: Clean Configuration Sandbox Checks
Use sandbox checks to verify if local configuration files are causing failures. Run Claude with config parameters redirected to a temporary folder:
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeThis routes CLAUDE_CONFIG_DIR to a scratch folder, bypassing global settings under ~/.claude, while starting from /tmp (which lacks project-level configurations or CLAUDE.md). This loads a clean session free of custom configs, hooks, or MCP tools.
- If the error disappears in this clean session: the issue lies in your
~/.claudeor project configurations. Restore components one by one until the error returns to identify the cause. - If the error persists: the root cause is external to configs (environment variables, network routes, or installation dependencies).
💡 Summary in one sentence: Isolate complex bugs using
claude --debug [mcp/hooks]to inspect runtime steps, or clean context sandboxing to verify if settings files are causing the issue.
08 Practice: Environment Diagnostics Audit
Step 1: Check your CLI build version
claude --versionExpected: Output prints the build number, e.g., 2.1.xxx (Claude Code). This confirms the binary is callable. If it logs command not found: claude, add the installation folder to your shell PATH (Chapter 02, defaults to ~/.local/bin on macOS/Linux).
Step 2: Run /doctor
claude/doctorExpected: Diagnostics log files check: installation health, schema validations, MCP servers, and memory sizes. All checks passing confirms configurations are clean. If errors are reported, press f to stream details back to Claude to assist in debugging.
Step 3: Confirm active credentials
/statusExpected: Logs your active credentials profile. Verify that subscription users display OAuth profiles rather than API keys. If it displays an API key incorrectly, run unset ANTHROPIC_API_KEY and clean shell profiles.
Step 4: Run a clean sandbox test (Optional)
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeExpected: The clean session loads without your default configurations, custom rules, or MCP tools (run /memory or /mcp to verify). This sandbox confirms if files are causing bugs. Note: Linux/Windows will prompt for login (creds are config-folder scoped), while macOS reads credentials from system Keychains. Exit once tested.
💡 Summary in one sentence: Triage environments using
claude --version,/doctor,/status, and sandbox checks;/doctoridentifies file issues while/statusverifies authentication profiles.
09 Summary
This article outlined a systematic approach to troubleshooting, triaging symptoms into actionable diagnostic steps.
Let's review the summary:
| Symptom | Diagnostic Step | Key Point |
|---|---|---|
| Category unclear | Match routing tables & run /doctor | Classify parameters before editing configs |
| Repeated logins / Organization error | Run /status to check active credentials | Residual export ANTHROPIC_API_KEY settings override OAuth |
| Ignored configs/hooks/MCP | Verify active parameters via /context, /hooks, /mcp | Check case capitalization and overrides |
| Lag, memory, search failures | Run /compact, restart CLI, or install system ripgrep | Typically caused by context window limits |
| API Error logs | Identify source: Server load, Quota, or Context size | Server load (wait), quota (top up), too long (/compact) |
| Obscure errors | Enable --debug flags or redirect CLAUDE_CONFIG_DIR | Inspect active logs and isolate variables |
You should now be able to: identify symptoms using routing tables, query environments using /doctor, check active credentials via /status, resolve API load errors, run debug logs, sandbox configurations to isolate variables, and submit reports via /feedback. Adopting this workflow replaces guesswork with methodical triaging.
With installation, optimization, and troubleshooting workflows complete, the remaining task is organizing the technical terms you have encountered.