Skip to content
, ,

Claude Code Not Working? Fixes for CLI, Desktop and VS Code (Nov 2026)

13–20 minutes
Winking woman in a terracotta hoodie in a library holding a white card with the Claude logo, hook text: 13 errors fixed fast

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.

TLDR

  • First: check status.claude.com, then run claude doctor in your shell or /doctor inside a session.
  • “command not found”: add ~/.local/bin to your PATH and open a new terminal.
  • Login loop: run /logout, restart, and check for a stray ANTHROPIC_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-mode to 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.

  1. Check the status page. Open status.claude.com. If there is an active incident, wait it out. Your settings are fine.
  2. Check your version. Run claude --version. A working install prints something like 2.1.329 (Claude Code).
  3. 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.
  4. 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.
  5. Confirm the login. Type /status to see which account or API key is active, and whether managed settings apply.
  6. Update. Run claude update. Many bugs below are already fixed in newer builds.
Quick answer: use 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.

  1. 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.
  2. Check PATH. Run echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin". No output means the folder is missing.
  3. Add it for zsh. Run echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc then source ~/.zshrc.
  4. Add it for bash. Use the same line with ~/.bashrc (or ~/.bash_profile on macOS bash).
  5. Open a new terminal. Run claude --version again.

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.exe that 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 c to 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 /login and check that your system clock is correct, since token checks depend on it.
  • macOS Keychain locked: claude doctor warns “macOS Keychain is not writable”. Run security unlock-keychain ~/Library/Keychains/login.keychain-db, then /logout and /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 /model to another model often works right away.

For a 429 rate limit error

  • Check the credential: run /status. A stray ANTHROPIC_API_KEY can route you to a low-tier API key.
  • Lower concurrency: avoid many parallel subagents, or set CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY lower.
  • 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.

  1. Read the reset time. It is printed in the message. Nothing you change locally resets it sooner.
  2. Check details. Run /usage to see your plan limits and reset times.
  3. Model-specific limit? An Opus or Sonnet limit only covers that family, so /model to a model outside it. Session and weekly limits are shared across all models.
  4. Need to keep going? Run /usage-credits to 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.json at the repo root, under mcpServers. Not inside .claude/, and not under a servers key like VS Code’s file.
  • Added to settings.json: settings.json does not read mcpServers. Use .mcp.json or claude 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 command or args resolve from where you launched Claude. Use absolute paths.
  • Connected but zero tools: choose Reconnect. If it stays at zero, run claude --debug=mcp and read ~/.claude/debug/<session-id>.txt.
  • Missing env vars: set a per-server env block in the .mcp.json entry.

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 press r.
  • 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. Run claude auto-mode defaults to see the rules.
  • Leave auto mode: press Shift+Tab to 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 in settings.json. There is no standalone hooks file outside plugins.
  • Wrong settings file: ~/.claude.json is 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, not bash.

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:

  1. Cancel. Press Ctrl+C. If it is frozen, close the terminal. Your chat is safe: claude --resume in the same folder brings it back.
  2. Shrink context. Run /compact, or restart between big tasks.
  3. Ignore build folders. Add large build directories to .gitignore.
  4. Rule out extensions. Start claude --safe-mode. It turns off CLAUDE.md, plugins, hooks and MCP servers for that session.
  5. 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 /clear between 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 set CLAUDE_CODE_GIT_BASH_PATH to C:\Program Files\Git\bin\bash.exe in the env block of settings.json. The file must be named bash.exe, not git-bash.exe.
  • “running scripts is disabled”: PowerShell blocks npm’s .ps1 shims. Use the PowerShell installer instead, or call claude.cmd.
  • Wrong install command: 'irm' is not recognized means 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 node shows /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 doctor in a terminal to see the real startup error.
  • Garbled text in the terminal: run /terminal-setup to 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 user from an empty folder.
  • Setting seems ignored: settings.local.json overrides settings.json. Check /status for managed settings from your org.
  • “claude update” or “claude doctor” hangs: on versions before 2.1.214, a folder at a path like ~/.zshrc caused this. Rerun the install script.
  • Auto-update keeps failing: run claude update in your shell to see the real error.
  • Still stuck: use /feedback to 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

Free weekly email

Get new AI guides every week

One short weekly email with our newest local AI, ComfyUI and AI tool guides. No spam, no pop-ups, just the good stuff.

Free. Unsubscribe anytime in one click. We only use your email to send this newsletter. See our privacy policy.

Winking woman in a terracotta hoodie in a library holding a white card with the Claude logo, hook text: 13 errors fixed fast