Claude Code not working? Most problems fall into a few groups: a missing claude command, a login loop, a 429, 529 or usage limit, or an MCP server, hook or permission rule in the way.
This guide gives the exact fix for each one, checked against the official docs on November 20, 2026. It covers the CLI, the Claude Desktop app and the VS Code extension.
The current release is v2.1.329 (November 19, 2026), and a few recent versions changed how limits and permissions behave.
- First: check status.claude.com, then run
claude doctorin your shell or/doctorinside a session. - “command not found”: add
~/.local/binto your PATH and open a new terminal. - Login loop: run
/logout, restart, and check for a strayANTHROPIC_API_KEY. - 429 / 529: wait, switch model with
/model, and confirm the active login with/status. A 529 does not use your quota. - Usage limit: wait for the reset time shown, check
/usage, or buy extra usage with/usage-credits. - Weird behaviour: start
claude --safe-modeto rule out MCP servers, hooks and plugins.
Start here: the 2-minute health check
Before you change any settings, rule out the simple causes. Many problems turn out to be an outage, an old version or the wrong login.
- Check the status page. Open status.claude.com. If there is an active incident, wait it out. Your settings are fine.
- Check your version. Run
claude --version. A working install prints something like2.1.329 (Claude Code). - Run the doctor from your shell. Run
claude doctor. It prints install health, invalid settings files and warnings with suggested fixes, without starting a session. - Run the doctor inside a session. Type
/doctor. It checks your install, settings, extensions and context use, and offers to apply fixes after you confirm. - Confirm the login. Type
/statusto see which account or API key is active, and whether managed settings apply. - Update. Run
claude update. Many bugs below are already fixed in newer builds.
claude doctor when Claude Code will not start, and /doctor when it starts but misbehaves. Then check /mcp for MCP servers and /hooks for hooks.Error-by-error fix table
Find the message you see, then jump to the section for full steps. The wording comes from the official troubleshooting and error reference pages.
| What you see | Likely cause | Fast fix |
|---|---|---|
command not found: claude or 'claude' is not recognized |
Install folder is not on PATH | Add ~/.local/bin to PATH, open a new terminal |
Native installation exists but ... is not in your PATH |
Installer could not edit PATH | Run the PATH command it prints |
OAuth error: Invalid code |
Code expired or was cut off | Retry fast, press c to copy the full URL |
API Error: 403 Request not allowed |
Inactive plan, missing Console role, or proxy | Check claude.ai/settings or your Console role |
This organization has been disabled |
Old ANTHROPIC_API_KEY overrides your plan |
unset ANTHROPIC_API_KEY |
API Error: Request rejected (429) |
Rate limit or low-tier key | /status, fewer parallel subagents |
Repeated 529 Overloaded errors |
API at capacity | Wait, or /model to switch |
You've hit your session limit / weekly limit |
Plan usage used up | Wait for reset, /usage, /usage-credits |
Request timed out |
Slow network or proxy | Raise API_TIMEOUT_MS |
Autocompact is thrashing |
A huge file refills context | Read files in chunks, /compact with a focus |
Auto-update failed · Run claude doctor |
Background update did not install | Run claude update |
Exec format error in WSL |
WSL1 native binary bug | Convert the distro to WSL2 |
Claude Code process exited with code 1 in VS Code |
CLI failed at startup | See the VS Code section below |
Fix “command not found” and PATH after install
The native installer puts the binary at ~/.local/bin/claude on macOS and Linux, and at %USERPROFILE%\.local\bin\claude.exe on Windows. If that folder is not on your PATH, your shell cannot find it.
The installer tells you this under “Setup notes”, but it does not change PATH for you. Follow these steps on macOS or Linux.
- Confirm the binary exists. Run
ls -la ~/.local/bin/claude. “No such file or directory” means there is no native install, so install Claude Code first. - Check PATH. Run
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin". No output means the folder is missing. - Add it for zsh. Run
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcthensource ~/.zshrc. - Add it for bash. Use the same line with
~/.bashrc(or~/.bash_profileon macOS bash). - Open a new terminal. Run
claude --versionagain.
On Windows, add %USERPROFILE%\.local\bin to your User PATH in Environment Variables, then open a fresh PowerShell window.
Note: the VS Code extension ships its own private copy of the CLI and does not add claude to PATH. If you only installed the extension, run the standalone installer to use claude in a terminal.
Two installs fighting each other
If claude runs an old version, you may have more than one install. Run which -a claude and npm -g ls @anthropic-ai/claude-code. Keep the native install and remove the rest:
- npm global:
npm uninstall -g @anthropic-ai/claude-code - WinGet:
winget uninstall Anthropic.ClaudeCode - Old Claude Desktop on Windows: update Desktop, because older builds registered a
Claude.exethat opens the app instead of the CLI.
Fix login and auth loops
When login fails and the cause is unclear, a clean re-login fixes most cases. Run /logout, close Claude Code, then start claude and sign in again.
- Browser does not open: press
cto copy the OAuth URL and paste it into your browser. - WSL2, SSH or containers: the browser shows a login code instead of redirecting. Paste it at the “Paste code here if prompted” prompt, or run
claude auth login, which reads the code from standard input. - WSL2 browser never opens: set
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe". - Asked to log in again and again: run
/loginand check that your system clock is correct, since token checks depend on it. - macOS Keychain locked:
claude doctorwarns “macOS Keychain is not writable”. Runsecurity unlock-keychain ~/Library/Keychains/login.keychain-db, then/logoutand/login.
The “organization disabled” error with an active plan
This one confuses many people. If an ANTHROPIC_API_KEY environment variable is set and approved, Claude Code uses that key instead of your Pro or Max login. With -p, the key is always used when present.
unset ANTHROPIC_API_KEY
claude
On Windows PowerShell, run Remove-Item Env:ANTHROPIC_API_KEY. Then delete the export line from ~/.zshrc, ~/.bashrc or your PowerShell $PROFILE so it does not come back.
Also note that the free claude.ai plan does not include Claude Code. You need Pro, Max, Team, Enterprise or a Console account.
Fix 429 rate limit and 529 overloaded
These two look alike but mean different things. A 429 means your requests were rejected for rate reasons. A 529 means the API itself is at capacity.
For a 529 overloaded error
- It is free: a 529 does not count against your usage quota.
- Wait a few minutes and retry. Claude Code already retries for you (10 times by default).
- Switch model: capacity is tracked per model, so
/modelto another model often works right away.
For a 429 rate limit error
- Check the credential: run
/status. A strayANTHROPIC_API_KEYcan route you to a low-tier API key. - Lower concurrency: avoid many parallel subagents, or set
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYlower. - Raise your tier: on the API, check your Console limits.
For scripts, CLAUDE_CODE_MAX_RETRIES sets the retry count. On slow networks, raise the 10-minute timeout with export API_TIMEOUT_MS=900000. Our full 429 and 529 guide covers the API side in depth.
Usage limit reached: 5-hour and weekly resets
On Pro and Max, Claude Code shares one usage pool with the Claude apps. Anthropic’s Pro help page says the session-based limit resets every five hours, and weekly caps can also apply.
The messages look like this:
You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
Since v2.1.312 (October 27, 2026), the app calls the session limit the “5-hour limit”, and VS Code shows the reset as a clock time.
- Read the reset time. It is printed in the message. Nothing you change locally resets it sooner.
- Check details. Run
/usageto see your plan limits and reset times. - Model-specific limit? An Opus or Sonnet limit only covers that family, so
/modelto a model outside it. Session and weekly limits are shared across all models. - Need to keep going? Run
/usage-creditsto buy extra usage on Pro or Max, or request it from an admin on Team and Enterprise.
Tip: resuming an old, long conversation can eat a big slice of the 5-hour limit. Recent builds warn you before that happens, so start fresh with /clear when the old context is not needed.
Fix MCP servers that fail
Run /mcp first. It lists each server, its connection status and whether you approved it for this project. Then match what you see:
- Server never appears: project servers belong in
.mcp.jsonat the repo root, undermcpServers. Not inside.claude/, and not under aserverskey like VS Code’s file. - Added to settings.json:
settings.jsondoes not readmcpServers. Use.mcp.jsonorclaude mcp add --scope user. - Shows as disabled: you dismissed the one-time approval. Approve it from
/mcp. - Fails to start in some folders: relative paths in
commandorargsresolve from where you launched Claude. Use absolute paths. - Connected but zero tools: choose Reconnect. If it stays at zero, run
claude --debug=mcpand read~/.claude/debug/<session-id>.txt. - Missing env vars: set a per-server
envblock in the.mcp.jsonentry.
Our Claude Code MCP setup guide walks through adding servers from scratch.
Permission prompts and auto mode blocks
Since v2.1.283, new terminal and VS Code sessions start in auto mode by default, where a classifier reviews actions in the background. That surprises people who expect a prompt for everything.
Why auto mode blocked an action
The classifier blocks risky actions by default, such as curl | bash, production deploys, git reset --hard and force pushes. Broad allow rules like Bash(*) are dropped while in auto mode.
- Retry once by hand: open
/permissions, go to Recently denied, and pressr. - Approve in chat: name the exact action, for example the branch to force-push. A vague “you can push” does not clear it.
- Allow it for good: add routine patterns to
autoMode.allow. Runclaude auto-mode defaultsto see the rules. - Leave auto mode: press
Shift+Tabto cycle back to Manual.
Three blocks in a row, or 20 in total, pause auto mode and bring prompts back.
Warning: after v2.1.302, claude -p and Agent SDK runs with no mode set start in Manual and deny anything that needs approval. Pass --allowedTools or --permission-mode auto. Never use bypassPermissions outside a container or VM.
Read our auto mode guide for the full rule system.
Hooks that error or never fire
Run /hooks to list every loaded hook. If yours is missing, Claude Code did not load it. The usual causes:
- Wrong file: hooks go under the
"hooks"key insettings.json. There is no standalone hooks file outside plugins. - Wrong settings file:
~/.claude.jsonis app state. Hooks belong in~/.claude/settings.json. - Matcher is an array: use one string such as
"Edit|Write". - Lowercase tool name: matching is case-sensitive, so use
Bash, notbash.
If the hook is listed but does not fire, start claude --debug and trigger it. The log shows which matchers were checked plus the exit code and output. Our hooks guide has working examples.
Slow, hanging or memory-heavy sessions
Large codebases and long chats use a lot of memory. Try these in order:
- Cancel. Press
Ctrl+C. If it is frozen, close the terminal. Your chat is safe:claude --resumein the same folder brings it back. - Shrink context. Run
/compact, or restart between big tasks. - Ignore build folders. Add large build directories to
.gitignore. - Rule out extensions. Start
claude --safe-mode. It turns off CLAUDE.md, plugins, hooks and MCP servers for that session. - Memory warning. Past 2.5 GB of heap, Claude Code warns you. Restart and run
claude --continue.
Search tools or @file not finding files? The bundled ripgrep may not run on your system. Install ripgrep from your package manager and set USE_BUILTIN_RIPGREP to 0.
If you see “Autocompact is thrashing”, a big file keeps refilling the window. Ask Claude to read it in chunks, or run /compact keep only the plan and the diff.
High token use
High token use usually means too much loads into each turn. Run /context to see what fills the window: system prompt, MCP tools, memory files, skills and messages.
- Too many MCP tools: disconnect servers you do not need in this project.
- Long CLAUDE.md: trim it to the rules that matter.
- Stale chat: use
/clearbetween unrelated tasks. - Big files: point Claude at a function or line range, not the whole file.
- Heavy side work: move it to a subagent with its own context window.
Our guide to reducing Claude Code token usage goes deeper on each trick.
Windows and WSL issues
Native Windows needs Windows 10 1809 or later. Git for Windows is now optional: without it, Claude Code uses the PowerShell tool instead of Bash.
- Git Bash not found: run
where.exe git, then setCLAUDE_CODE_GIT_BASH_PATHtoC:\Program Files\Git\bin\bash.exein theenvblock of settings.json. The file must be namedbash.exe, notgit-bash.exe. - “running scripts is disabled”: PowerShell blocks npm’s
.ps1shims. Use the PowerShell installer instead, or callclaude.cmd. - Wrong install command:
'irm' is not recognizedmeans you are in CMD, not PowerShell. Use the CMD command from the setup docs. - WSL1 “Exec format error”: convert the distro to WSL2 with
wsl --set-version <distro> 2. - WSL using Windows Node: if
which nodeshows/mnt/c/, install Node inside Linux, or switch to the native installer. - Slow or partial search in WSL: move the project from
/mnt/c/to your Linux home folder.
VS Code and Desktop app issues
The VS Code extension needs VS Code 1.94.0 or later and a paid plan or Console account. Common fixes:
- Spark icon missing: open a file (a folder alone is not enough), reload the window, and leave Restricted Mode. You can also click “Claude Code” in the status bar.
- Extension will not install: check your VS Code version and install from the Marketplace directly.
- Conflicting AI extensions: temporarily disable tools like Cline or Continue.
- “Process exited with code 1”: run
claude doctorin a terminal to see the real startup error. - Garbled text in the terminal: run
/terminal-setupto turn off GPU acceleration. - Cloud credentials work in terminal only: the IDE did not inherit your shell. Set the variables in IDE settings or launch VS Code from that terminal.
In the Claude Desktop app on Windows, Desktop does not read PowerShell profiles. If a session cannot find tools like npm, set PATH in your Windows environment variables, then quit and reopen Desktop. Session isolation also needs Git, so check git --version.
Update or reinstall cleanly
Native installs update themselves in the background. Homebrew and WinGet do not. See our full update guide for every method.
| Install method | Update command |
|---|---|
| Native installer | claude update |
| Homebrew | brew upgrade claude-code (or claude-code@latest) |
| WinGet | winget upgrade Anthropic.ClaudeCode |
| npm | npm install -g @anthropic-ai/claude-code@latest |
| apt | sudo apt update && sudo apt upgrade claude-code |
If a new release breaks something, switch to the stable channel. Set "autoUpdatesChannel": "stable" in settings.json, which serves a build about a week old and skips releases with major regressions.
Clean reinstall on macOS or Linux
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
curl -fsSL https://claude.ai/install.sh | bash
On Windows PowerShell, reinstall with irm https://claude.ai/install.ps1 | iex.
Warning: deleting ~/.claude and ~/.claude.json wipes your settings, MCP configs and session history. Only do it as a last resort.
Troubleshooting when the fix does not stick
If the problem keeps coming back, narrow it down step by step:
- Problem gone in safe mode: one of your MCP servers, hooks, plugins or CLAUDE.md files causes it. Turn them back on one at a time.
- Problem stays in safe mode: test a clean config. Run
CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources userfrom an empty folder. - Setting seems ignored:
settings.local.jsonoverridessettings.json. Check/statusfor managed settings from your org. - “claude update” or “claude doctor” hangs: on versions before 2.1.214, a folder at a path like
~/.zshrccaused this. Rerun the install script. - Auto-update keeps failing: run
claude updatein your shell to see the real error. - Still stuck: use
/feedbackto report it, and check the GitHub issues for known bugs.
Billing and subscription problems are not code bugs. Sign in at claude.ai, click your initials, and choose Get help.
Frequently Asked Questions
Why does it say “claude: command not found” right after installing?
The installer put claude in ~/.local/bin, but that folder is not on your PATH. Add it to your shell config and open a new terminal.
What is the difference between claude doctor and /doctor?
claude doctor runs from your shell without starting a session, so it works when Claude Code will not launch. /doctor runs inside a session and can apply fixes after you confirm.
Does a 529 overloaded error use up my usage?
No. A 529 does not count against your quota. Wait a few minutes or switch models with /model.
When does my Claude Code usage limit reset?
The limit message prints the exact reset time. The session limit, now called the 5-hour limit, resets every five hours, and weekly limits reset at the time shown in /usage.
Why is Claude Code using my API key instead of my Pro or Max plan?
An approved ANTHROPIC_API_KEY environment variable takes priority over your subscription login. Unset it, remove it from your shell profile, and check /status.
Why does Claude Code run commands without asking me?
Since v2.1.283, terminal and VS Code sessions start in auto mode by default. Press Shift+Tab to switch to Manual, or set permissions.defaultMode in your user settings.
Is it better to use Claude Code on native Windows or WSL?
Native Windows is fine for Windows projects and no longer needs Git. Pick WSL2 if you use Linux toolchains or want sandboxing, and keep projects on the Linux file system for speed.
Sources
- Claude Code docs: Troubleshooting
- Claude Code docs: Troubleshoot installation and login
- Claude Code docs: Error reference
- Claude Code docs: Debug your configuration
- Claude Code docs: Permission modes
- Claude Code docs: Advanced setup
- Claude Code docs: VS Code
- Claude Code changelog
- Claude Help Center: About Claude’s Pro plan usage
- Claude status page




