When Claude Code is not working, start by running /doctor inside a session, or claude doctor from your shell if claude won't start at all. It checks your installation, settings, extensions and context usage and proposes fixes. If that doesn't explain it, match your symptom below: most problems are a PATH issue, a login conflict, a permission mode you didn't expect, an MCP config mistake, or a session that has grown too large.
The fixes here come from Anthropic's Troubleshooting, Troubleshoot installation and login and Debug your configuration pages, checked on 24 October 2026.
Where should you start when Claude Code isn't working?
Pick the row that matches what you see:
| Symptom | Likely cause | Section below |
|---|---|---|
command not found: claude or 'claude' is not recognized |
Install folder not on PATH | Install problems |
syntax error near unexpected token '<' during install |
Installer downloaded a web page | Install problems |
Login loops, OAuth error, 403 Forbidden |
Expired login, wrong role, proxy | Login problems |
| "This organization has been disabled" | ANTHROPIC_API_KEY overriding your plan |
Login problems |
| Claude edits files without asking | Session started in auto mode | Permission surprises |
Tool calls denied in claude -p after an update |
Non-interactive runs now start in Manual mode | Permission surprises |
| MCP server missing or shows zero tools | Approval, paths or config location | MCP problems |
| High CPU or memory, hangs, search finds nothing | Large context, extensions, ripgrep | Performance problems |
Three commands answer most "why didn't my setting work?" questions:
/contextshows everything in the context window, so you can confirm yourCLAUDE.md, skills and MCP tools loaded at all./statusshows active settings sources, including whether managed settings apply, and which login is in use./permissionsshows the allow and deny rules in effect.
How do you fix Claude Code install problems?
command not found: claude. The installer worked but its folder isn't on your PATH. On macOS and Linux it puts claude at ~/.local/bin/claude; on Windows, at %USERPROFILE%\.local\bin\claude.exe. Check the file exists, then add the folder. For Zsh, the macOS default:
ls -la ~/.local/bin/claude
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
If the echo line fails with permission denied, your shell config file is read-only or owned by another user; the docs suggest chmod u+w ~/.zshrc if you own it.
Note that the VS Code extension bundles its own private copy of the CLI and doesn't add claude to your PATH. If you only installed the extension, run the standalone installer to use claude in a terminal.
Conflicting installs. Multiple copies cause version mismatches. Run which -a claude to list them, and check ~/.local/bin/claude (native), ~/.claude/local/ (an old local npm install) and npm -g ls @anthropic-ai/claude-code.
Installer returns HTML. An error like syntax error near unexpected token '<' means the download was a web page, not the script. The official commands are:
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
Wrong command on Windows. 'irm' is not recognized means you are in CMD, not PowerShell, and A parameter cannot be found that matches parameter name 'fsSL' means you ran the macOS/Linux command in PowerShell. The Claude Code on Windows guide covers native Windows, WSL and Git Bash setup in full.
Homebrew says the cask doesn't exist. Your local index is stale. Run brew update, then brew install --cask claude-code. The claude-code cask tracks the stable channel, about a week behind; claude-code@latest gets the newest release.
Auto-update failed · Run claude doctor in the footer. Run claude update from your shell.
How do you fix login and authentication errors?
Reset your login first. The docs say a clean re-authentication "resolves most cases":
- Run
/logout. - Close Claude Code.
- Run
claudeand log in again.
If the browser doesn't open, press c to copy the login URL and open it yourself.
OAuth error: Invalid code. The code expired or got cut off while copying. Retry and finish quickly. Over SSH, the browser may open on the wrong machine, so copy the URL into your local browser.
Login fails in WSL2, SSH or containers. The browser can't redirect back, so it shows a code. Paste it at the Paste code here if prompted prompt. If pasting does nothing, run claude auth login, which reads the code from standard input. In WSL2 you can also set BROWSER to your Windows browser path.
API Error: 403 Request not allowed. On Pro or Max, check your subscription is active at claude.ai/settings. On a Console account, you need the "Claude Code" or "Developer" role. Corporate proxies can also cause it; see the network configuration docs.
"This organization has been disabled" with an active subscription. An ANTHROPIC_API_KEY in your environment is overriding your subscription. The docs note that in -p mode "the key is always used when present." Remove it:
unset ANTHROPIC_API_KEY
claude
Then delete the export ANTHROPIC_API_KEY=... line from ~/.zshrc, ~/.bashrc or ~/.profile, and run /status to confirm.
Asked to log in again often. Run /login, and check your system clock is accurate, since token validation depends on it.
Keychain warnings on macOS. If claude doctor reports macOS Keychain is not writable, Claude Code has been saving your login to a plaintext file instead. Unlock the keychain, run claude doctor again, then run /logout and /login.
Why does Claude Code act without asking, or refuse tools?
It edits files and runs commands without asking. In Claude Code v2.1.283 or later, new terminal and VS Code sessions start in auto mode by default unless something else sets a mode. In auto mode a classifier reviews actions instead of prompting you. To start in the mode that asks every time, set defaultMode under permissions in ~/.claude/settings.json:
{
"permissions": {
"defaultMode": "manual"
}
}
Or launch with claude --permission-mode manual. The permission modes docs list every mode and which one a session starts in.
Tool calls denied in claude -p or SDK runs after an update. From v2.1.302, non-interactive runs with no mode set start in Manual mode, and calls needing approval are denied. Add allow rules, for example --allowedTools "Bash(npm test)", or pass --permission-mode auto.
A setting seems ignored. Settings merge across scopes. settings.local.json overrides settings.json, and both override ~/.claude/settings.json; managed settings apply first when present. Another common trap: putting permissions, hooks or env in ~/.claude.json, which holds app state. Those keys belong in ~/.claude/settings.json.
A hook never fires. Run /hooks. Usual causes are a matcher written as an array instead of a string, a lowercase tool name (bash instead of Bash), or hooks in a standalone file instead of under "hooks" in settings.json. The hooks guide has working examples.
Why won't an MCP server load?
Run /mcp to see each server, its status and whether it is approved for this project. Then check:
- Project servers need a one-time approval. If you dismissed the prompt, approve the server from
/mcp. - Relative paths break. A relative path in
commandorargsresolves against the folder you launched Claude Code from, not the.mcp.jsonfile. Use absolute paths for local scripts. - Wrong file location or key. Project config goes at the repository root as
.mcp.json, not inside.claude/, with servers undermcpServers. VS Code'sserverskey doesn't work, andsettings.jsondoesn't read anmcpServerskey at all. - Connected but zero tools. Select Reconnect in
/mcp. If it stays at zero, runclaude --debug=mcpand read the server's stderr in~/.claude/debug/<session-id>.txt.
The Claude Code MCP guide covers adding servers and scopes.
How do you fix slowness, high memory and hangs?
High CPU or memory. The docs suggest:
- Run
/compactregularly to shrink context. - Close and restart Claude Code between major tasks.
- Add large build directories to
.gitignore. - Restart with
claude --safe-mode, which turns off customizations likeCLAUDE.md, skills, plugins, hooks and MCP servers. If usage drops, one of those is the cause.
Above 2.5GB of heap memory, Claude Code shows a critical memory warning. Restart and run claude --continue to resume in a fresh process.
Autocompact is thrashing. A file or tool output keeps refilling the context right after compaction. Ask Claude to read the big file in smaller chunks, run /compact with a focus such as /compact keep only the plan and the diff, move the work to a subagent, or /clear if you no longer need the history. The context window guide explains how compaction works.
Frozen session. Press Ctrl+C. If that fails, close the terminal; claude --resume in the same folder picks the conversation back up.
Search or @file finds nothing. The bundled ripgrep may not run on your system. Install your platform's ripgrep (for example brew install ripgrep) and set USE_BUILTIN_RIPGREP to 0 in your environment or the env block of settings.json. On WSL, projects under /mnt/c/ search slowly and can miss results; moving the project to the Linux filesystem helps.
Garbled text in VS Code or Cursor's terminal. Run /terminal-setup to turn off the terminal's GPU acceleration.
What if nothing here fixes it?
- Run
/feedbackinside Claude Code to report the problem to Anthropic. - Search or open an issue on the Claude Code GitHub repository, with your OS, install command and full error.
- For account or billing problems, sign in at claude.ai, click your initials and select Get help, as described in How to get support.
Once things work again, keep the fix. Kipt stores prompts as Markdown in a private GitHub repo you own, so a "diagnose this Claude Code error" prompt with a {{error_message}} blank is a Cmd+K search away next time something breaks.