Run claude doctor first: it reports install health, PATH, duplicate installations, invalid settings files, and credential state in one command. Then check version, authentication with /status, configuration with /context and /doctor, and network reachability. If the cause is still not obvious, relaunch with claude --safe-mode, which disables every customization at once. Reinstalling is almost never the fix and destroys the evidence that would have told you what was wrong.
claude doctorfirst, always. It answers three of the six.--safe-modedisables every customization in one flag. Use it to bisect.~/.claude.jsonand~/.claude/settings.jsonare different files. This trips up everyone.- One invalid entry can make Claude Code reject an entire settings file.
/statustells you which credential is actually billing.- Do not reinstall first. It destroys the evidence.
The order
Two minutes, top to bottom. Stop at the first check that says something surprising.
# 1. install health, PATH, duplicate installs, settings validity, credentials
claude doctor
# 2. version - the bug may already be fixed
claude --version
# 3. which binary is actually running, and are there several?
which -a claude
# 4. is your config even valid JSON?
jq . ~/.claude/settings.json
jq . .claude/settings.json
jq . .claude/settings.local.json
# 5. can you reach the API at all?
curl -I https://api.anthropic.com/doctor # setup checkup, proposes fixes it applies after you confirm
/status # active settings sources, and which credential is billing
/context # what actually loaded: memory, skills, MCP tools, subagents
/mcp # server connection status
/hooks # hooks registered for this session
/permissions # the allow and deny rules actually in effectSymptom to cause
| Symptom | Likely cause | Fix |
|---|---|---|
command not found | PATH, or a moved Node prefix | See the dedicated guide |
| Starts, then exits immediately | Auth failure | /login; check ANTHROPIC_API_KEY |
| Asks to log in every launch | Credential store not writable | macOS: unlock the login keychain |
| Billed per token on a subscription | ANTHROPIC_API_KEY is set | unset it and delete the export |
403 Forbidden after login | Subscription inactive, or missing Console role | Check claude.ai settings, or ask an admin |
| Settings have no effect | Wrong file, or a schema error | /status, then claude doctor |
| Hooks never fire | Matcher is an array, or lowercase | Single string, "Edit|Write", capitalized |
| MCP server missing | Failed to start, or awaiting approval | /mcp, then claude --debug=mcp |
| Skill never appears | File is name.md, not name/SKILL.md | Use a folder with SKILL.md inside |
| Very slow, or high memory | Huge context, or an extension | /context, then --safe-mode |
| Forgets things mid-session | The window filled and compacted | /compact deliberately, or /clear |
| Cannot see files it should | Launched from the wrong directory | Start at the repo root, or /add-dir |
| Search misses files that exist | Bundled ripgrep will not run | Install ripgrep, set USE_BUILTIN_RIPGREP=0 |
| Boxes or smeared glyphs in an IDE terminal | GPU renderer | /terminal-setup |
| Errors on every request | Service incident | status.claude.com |
| Worked yesterday, not today | Auto-update | claude --version, then check the changelog |
Configuration that silently does nothing
This is the category that wastes the most time, because there is no error. You wrote the rule, Claude Code read a different file, and nothing tells you.
The four traps worth memorising.
| You did | What happened |
|---|---|
Put permissions, hooks, or env in ~/.claude.json | That file holds app state and UI toggles. Those keys belong in ~/.claude/settings.json. |
Set a key in settings.json that is also in settings.local.json | settings.local.json wins. Both beat ~/.claude/settings.json. |
| Wrote a hook matcher as an array | Schema error. Claude Code rejects the whole file, so every other hook in it stops too. |
Wrote a matcher as "bash" | Matching is case-sensitive. Tool names are Bash, Edit, Write, Read. |
# valid JSON?
jq . ~/.claude/settings.json && echo OK
# which sources are active, including any managed policy
# (inside a session)
/status
# did the memory file, skills and MCP tools actually load?
/contextIsolate it: safe mode, then a clean config
When the cause is not obvious, stop reading files and bisect. Two commands cover the whole surface.
Disable every customization at once
claude --safe-modeSafe mode launches with CLAUDE.md, skills, plugins, hooks, MCP servers, and custom commands and agents all disabled. Authentication, model selection, built-in tools, and permissions work normally. If the problem disappears, one of those surfaces is the cause and the targeted checks above will find which.
If it persists, bypass your configuration entirely
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeThis session loads nothing from ~/.claude and, because /tmp has no .claude folder, no project configuration either. Expect first-run setup screens; seeing them confirms the clean directory is in effect. On Linux and Windows you will be asked to log in again, since credentials live under the config directory. On macOS they come from the Keychain and carry over.
Reintroduce one thing at a time
Copy files into the temporary directory one by one, or launch from your project again, until the problem returns. That is your culprit. If the problem survives even the clean session, the cause is outside your user and project configuration: check managed settings with /status, then environment variables.
Slow, hung, or eating memory
- Run
/compact. Most "Claude Code got slow" reports are a context window that has been growing for hours. - Add large build directories to
.gitignoreso they stop being walked. - Restart between major tasks.
claude --resumein the same directory picks the conversation back up, so nothing is lost. - Relaunch with
claude --safe-mode. If memory drops, a plugin, MCP server, or hook is responsible. - If memory stays high, run
/heapdump. It writes a heap snapshot and a-diagnostics.jsonbreakdown to your Desktop and prints a summary.
One error worth recognising by name: Autocompact is thrashing: the context refilled to the limit.... Compaction succeeded and a file or tool output immediately refilled the window several times in a row, so Claude Code stopped retrying. Ask for a line range instead of a whole file, run /compact with a focus that drops the large output, move the work to a subagent, or /clear.
Things that look like bugs and are not
- It cannot see a file outside the launch directory. That is working-directory scope, and it is a feature. Use
--add-dir,/add-dir, or/cd. - A subdirectory
CLAUDE.mdseems ignored. Those load on demand, when Claude reads a file in that directory with the Read tool, not at session start. - The Explore and Plan agents ignore
CLAUDE.md. By design. Restate the instruction in your delegating prompt. - It forgot a decision from earlier. The window filled and older material was compacted. Compact deliberately at task boundaries instead.
- It refused an action. A deny rule matched, or a PreToolUse hook exited 2. Both are the system working.
- Permission prompts stopped appearing. Check the mode. Shift+Tab cycles them and is easy to hit by accident.
- A large table is cut off in the terminal. Tables over 200 rows render the first 200 with a "more rows not shown" line. The full table is still in the conversation.
When to actually reinstall
Almost never, and only after the checks above. If you do, your configuration and history live outside the package and survive it.
# these survive a reinstall, deliberately
# ~/.claude/ settings, memory, sessions, commands, skills
# ~/.claude.json app state and per-project MCP entries
# remove duplicates first, then install the native binary
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local
curl -fsSL https://claude.ai/install.sh | bash
claude doctorQuestions people ask
Run claude doctor from your shell. It reports install health, PATH, duplicate installations, invalid settings files, and credential state in one read-only command, which covers three of the six common causes without starting a session.
claude doctor runs from the shell and prints read-only diagnostics, so it works when Claude Code will not start. /doctor runs inside a session and goes further: it flags invalid settings, duplicate subagent names, unused extensions, and redundant CLAUDE.md content, and proposes fixes it applies only after you confirm.
Three usual causes. The keys are in ~/.claude.json, which holds app state, instead of ~/.claude/settings.json. A closer scope such as settings.local.json overrides them. Or a schema error, like a hook matcher written as an array, made Claude Code reject the entire file. Run /status and claude doctor to see which.
Launch with claude --safe-mode, which disables CLAUDE.md, skills, plugins, hooks, MCP servers, and custom commands and agents in one flag while leaving auth, models, tools, and permissions working. If the problem disappears, bisect from there.
The credential store is not persisting. On macOS this is usually a locked login keychain: run claude doctor to check Keychain access, then security unlock-keychain ~/Library/Keychains/login.keychain-db. Also check that your system clock is accurate, since token validation depends on it.
It is scoped to the directory you launched it from. Start at the repository root, add another directory with --add-dir or /add-dir, or relocate the session with /cd, which also loads the new directory CLAUDE.md.
The bundled ripgrep binary may not run on your system. Install your platform ripgrep package, then set USE_BUILTIN_RIPGREP to 0 in your environment or the env block of settings.json, and confirm with claude doctor that the Search line shows your system path.
Almost never, and not first: reinstalling destroys the evidence that would have told you what was wrong. Work through doctor, version, auth, configuration, network, and safe mode. If you do reinstall, remove duplicate installs first and use the native installer.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.