Troubleshooting — Diagnose & Fix

Systematic first moves, then the most common failures by category.

First Moves, Always

claude doctor        # full diagnostic: install, config, connectivity
claude --version     # many bugs are just "you're 3 weeks behind"
claude update
/status              # inside a session: account, model, plan
/context             # if behavior degrades mid-session
claude --debug       # verbose logging for gnarly cases

/debug-config (or asking Claude “why isn’t my hook firing?”) — Claude Code can debug its own configuration; settings precedence issues are the #1 config bug.

Install & Login

Symptom	Fix
The token '&&' is not a valid statement separator	You ran the CMD installer in PowerShell — use irm https://claude.ai/install.ps1 | iex
'irm' is not recognized	You’re in CMD, not PowerShell
Bash tool missing on Windows	Install Git for Windows (otherwise PowerShell is used as the shell tool)
Login loops / wrong account	/login to re-auth; check /status
Homebrew/WinGet install feels stale	Those don’t auto-update: brew upgrade claude-code / winget upgrade Anthropic.ClaudeCode

Session Behavior

Symptom	Likely cause → fix
Slow, forgetful responses late in session	Context near full → /context, then /compact or /clear (09)
First turn after a break is very slow	Cache expired — normal (54)
CLAUDE.md edits “not working”	They load at session start — /clear or restart
Hook not firing	Check scope/matcher in settings; trust dialog accepted?; disableAllHooks set?
Skill not appearing	Frontmatter description missing/vague; wrong directory; /reload-plugins for plugin skills
Permission prompt for something you allowed	Rule syntax — Bash(npm *) matches npm test but not npm test (double space) or chained npm test && rm x; chains need each part allowed
--dangerously-skip-permissions refuses to run	Blocked as root/sudo outside a recognized sandbox — use the devcontainer
Session picker can’t find a -p session	Headless sessions are hidden — resume by ID from the same directory
Two terminals resumed the same session	Messages interleave into one transcript — fork instead: claude --continue --fork-session

MCP

Symptom	Fix
Server tools missing	/mcp → check connection state; stdio servers: is the command on PATH?
Tools there but Claude “can’t see” them	Deferred by tool search (normal — loaded on demand); ENABLE_TOOL_SEARCH=false to force upfront
Server keeps disconnecting	Check the server process logs; HTTP session expiry; each reconnect can cost cache if tools aren’t deferred
Plugin not found in marketplace	/plugin marketplace update claude-plugins-official

Sandbox

Covered in depth in 16-sandboxing-and-security.md: jest --no-watchman, docker * → excludedCommands, Go CLIs TLS on macOS → excludedCommands, WSL1 → upgrade to WSL2.

Model & API Errors

Error	Meaning
Model "<name>" is not a recognized model id	Typo or unavailable — use an alias (sonnet, opus, fable)
restricted by your organization's settings	Admin allowlist (availableModels / org restrictions)
Rate limit / overloaded	Wait or /model to a different family; fast mode auto-falls-back to standard speed
Safety fallback on Fable	Flagged request re-runs on Opus automatically — expect one uncached turn

Getting Help

• /help in session; ask Claude itself — “how do I configure X in Claude Code?” is answered by a built-in docs agent
• Full error reference: https://code.claude.com/docs/en/errors
• Bugs: /bug or https://github.com/anthropics/claude-code/issues
• Community: Anthropic Discord

🧠 Quick Recall

• Trick: “Doctor first: claude doctor → --version → /status → /context.”

👨‍🏫 Teach It

• Do: break something on purpose (bad settings key) and walk the checklist.
• They’ll trip on: googling before asking Claude Code itself — it debugs its own config.

---

Learning path: ⬅ 54-prompt-caching-deep-dive.md · Index · ➡ 56-enterprise-deployment.md