Claude Code troubleshooting: fixes for the most common problems
By Shubhranshu, creator of claudeagents · Last reviewed
Most Claude Code problems fall into a few groups: installation and PATH, signing in, usage limits, sessions that get slow or confused, and tools like MCP servers or hooks that don't load. This page lists the fixes for each, starting with the two commands that diagnose most issues.
Error messages and fixes were checked against Anthropic's troubleshooting documentation on 16 November 2026.
Start here: two diagnostic commands#
claude doctor(from your shell) checks your installation, auto-updates and settings files, and lists warnings with suggested fixes. Inside a session,/doctordoes the same and offers to apply the fixes./statusshows your version, model, account and connection, so you can confirm you're signed in to the account you think.
Also check you're up to date: claude --version, then claude update.
Installation problems#
| Problem | Fix |
|---|---|
command not found: claude | Open a new terminal. If it persists, add ~/.local/bin to your PATH (Mac and Linux) or %USERPROFILE%\.local\bin (Windows). |
syntax error near unexpected token '<' | The installer returned a web page, usually because of a proxy or filter. Try another network or use Homebrew, WinGet or npm. |
irm is not recognized (Windows) | You're in CMD, not PowerShell. Use the CMD installer line or open PowerShell. |
EACCES: permission denied | Don't install with sudo. Use the native installer, or fix the npm folder's ownership. |
Auto-update failed in the footer | Run claude update from your shell. |
| Two different versions appear | You have two installs, for example npm and native. Remove one; claude doctor shows which is which. |
Full install steps are in the installation guide.
Sign-in and account problems#
- Asked to upgrade, or Claude Code isn't available: the free Claude plan doesn't include Claude Code. You need Pro, Max, Ultra, Team or Enterprise, or a Console account. See is Claude Code free?.
- Wrong account or stuck login: run
/logout, then/login, and finish the sign-in in your browser. - An API key is used instead of your subscription: if
ANTHROPIC_API_KEYis set in your environment, Claude Code can use it and bill the Console account. Remove it from your shell profile if you want to use your plan. - 403 errors in the desktop app's Code tab: sign out and back in, restart the app, and check your plan is active.
Usage limits#
- "You've hit your session limit" or "weekly limit": your plan's usage window is used up. The message shows when it resets. Run
/rate-limit-optionsto wait and continue automatically, add usage credits, or upgrade. - "You've hit your Opus limit": switch to another model with
/modelto keep working. - Limits run out faster than expected: long sessions resend the whole conversation with every request. Run
/usageto see what's using your limits,/clearbetween tasks, and see how to save tokens.
Slow, stuck or confused sessions#
- Claude forgets earlier instructions or repeats mistakes: the context is full. Run
/compactwith a hint, such as/compact keep the API design decisions, or start fresh with/clear. - Claude goes the wrong way: press Esc to stop, then type a correction. Use
/rewindto undo the edits. - A command hangs: press Ctrl+C to interrupt it, or Ctrl+B to move a long-running command to the background.
- The screen looks garbled: press Ctrl+L to redraw it.
- Shift+Enter sends instead of adding a new line: run
/terminal-setuponce.
MCP servers, hooks and skills#
- An MCP server doesn't show up: run
/mcpto see its status and errors, and reconnect with/mcp reconnect <server>. Check the server's command runs on its own in your terminal. See MCP setup. - A hook doesn't run: run
/hooksto check it's registered, then start withclaude --debug-file ./debug.txtand look for errors. See the hooks guide. - A new skill doesn't appear in the slash menu: run
/reload-skills, and check it's saved as.claude/skills/<name>/SKILL.md. - A plugin installed but does nothing: run
/reload-plugins, then check the Errors tab in/plugin. - A setting is ignored:
claude doctorreports invalid settings files. Remember that managed settings and deny rules override your own.
Windows and WSL#
- Install Git for Windows so Claude can use Git Bash; without it, Claude uses PowerShell.
- If Claude can't find Git Bash, set its path in
~/.claude/settings.jsonunderenvasCLAUDE_CODE_GIT_BASH_PATH. - In WSL, install and run Claude Code inside the Linux terminal, not from PowerShell.
Claude Code does not support 32-bit Windows: open the normal Windows PowerShell, not the (x86) one.
Still stuck?#
Run /bug inside Claude Code to send a report to Anthropic. You choose how much of the conversation to include. For billing questions, use Get help in your claude.ai account menu. Anthropic's troubleshooting and install troubleshooting pages list every error message.
Frequently asked questions
Why does my terminal say claude: command not found?
The install folder isn't on your PATH. Open a new terminal first. If it still fails, add ~/.local/bin (Mac and Linux) or %USERPROFILE%\.local\bin (Windows) to your PATH, then open a new terminal.
How do I fix Claude Code login problems?
Run /logout, then /login, and finish signing in in your browser. Check your plan includes Claude Code (Pro or higher), and remove ANTHROPIC_API_KEY from your environment if you meant to use your subscription.
Why is Claude Code slow or forgetting things?
The conversation has grown too long. Run /compact to summarize it, or /clear to start fresh for a new task. Long sessions also use up your plan limits faster.
What does claude doctor do?
claude doctor checks your installation, updates and settings files without starting a session, and suggests fixes for anything wrong. Inside a session, /doctor can apply the fixes for you.
How do I report a Claude Code bug?
Run /bug in a Claude Code session. You choose how much of the session to include and confirm before anything is sent to Anthropic.