Black Friday sale: 85 Claude Code agents for $29 one-time · lifetime updatesGet access →

Claude Code troubleshooting: fixes for the most common problems

Updated · 9 min read

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, /doctor does the same and offers to apply the fixes.
  • /status shows 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#

Claude Code installation errors
ProblemFix
command not found: claudeOpen 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 deniedDon't install with sudo. Use the native installer, or fix the npm folder's ownership.
Auto-update failed in the footerRun claude update from your shell.
Two different versions appearYou 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_KEY is 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-options to wait and continue automatically, add usage credits, or upgrade.
  • "You've hit your Opus limit": switch to another model with /model to keep working.
  • Limits run out faster than expected: long sessions resend the whole conversation with every request. Run /usage to see what's using your limits, /clear between tasks, and see how to save tokens.

Slow, stuck or confused sessions#

  • Claude forgets earlier instructions or repeats mistakes: the context is full. Run /compact with 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 /rewind to 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-setup once.

MCP servers, hooks and skills#

  • An MCP server doesn't show up: run /mcp to 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 /hooks to check it's registered, then start with claude --debug-file ./debug.txt and 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 doctor reports 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.json under env as CLAUDE_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.

Sources

Keep reading