Want an AI that works for you 24/7? Get the Free Blueprint href="/blueprint">Meet your Chief AI Officer →rarr;
Troubleshooting

Step-by-step solutions for the most common Claude Code problems. From installation issues to authentication errors to performance problems—find your fix here.

Updated February 10, 2026 · 12 min read

To fix Claude Code not working, first run claude --version to check your installation, then claude doctor to diagnose issues. The most common fixes are: update Node.js to v18+, reinstall with npm install -g @anthropic-ai/claude-code, or reauthenticate with claude auth.

Find your specific problem below and follow the step-by-step solution.

Quick Diagnostic

Run claude doctor from your terminal. It checks your installation, configuration, and connections, then reports any issues it finds. You can also use the --verbose flag for detailed logging or --mcp-debug to diagnose MCP server configuration issues.

New to Claude Code? Watch the free CAIO Blueprint to see it in action.

Installation Problems

"claude: command not found"

Your terminal can't find the Claude Code command. This usually means Node.js isn't installed or the global npm package isn't in your PATH.

Solution

  1. Check if Node.js is installed: node --version
    Should show v18 or higher. If not, install from nodejs.org
  2. Reinstall Claude Code: npm install -g @anthropic-ai/claude-code
  3. Close and reopen your terminal (this refreshes PATH)
  4. Try again: claude

"Permission denied" when installing

npm doesn't have permission to install global packages.

Solution (Mac/Linux)

  1. Don't use sudo. Instead, fix npm permissions:
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
  2. Add to your shell config (~/.zshrc or ~/.bashrc):
    export PATH=~/.npm-global/bin:$PATH
  3. Reload: source ~/.zshrc (or restart terminal)
  4. Reinstall: npm install -g @anthropic-ai/claude-code

"Node.js version too old"

Claude Code requires Node.js 18 or higher.

Solution

  1. Check your version: node --version
  2. If it's below v18, update Node.js from nodejs.org
  3. Or use nvm to manage versions:
    nvm install 20
    nvm use 20

Authentication Problems

"Authentication failed" or "Invalid API key"

Claude can't verify your identity or your API key isn't working.

Solution

  1. Run claude auth to reauthenticate
  2. If using API directly, check your environment variable:
    echo $ANTHROPIC_API_KEY
  3. Verify your account has credits at console.anthropic.com
  4. If key was recently created, wait a few minutes for propagation

"Rate limit exceeded"

You've hit your usage limits.

Solution

  1. Run /usage to see your current limits
  2. Wait for your rate limit to reset (usually 1 minute for short-term limits)
  3. If hitting daily limits, consider upgrading your plan
  4. Use /model haiku for simpler tasks—it has higher limits

Performance Problems

Claude is responding very slowly

Long conversations use more context, which slows responses. The model you're using also affects speed.

Solution

  1. Check context usage: /cost
  2. If context is high, compact it: /compact
  3. Or start fresh: /clear
  4. For simple tasks, switch to a faster model: /model haiku (Haiku 4.5 is the fastest)
  5. If using Opus 4.6, expect slower responses -- it's the most capable but also the most thorough
  6. Check status.anthropic.com -- high traffic periods can cause slowdowns

Claude forgets things from earlier in the conversation

The context window is full and older messages are being compressed or dropped.

Solution

  1. Use /compact with instructions about what to keep:
    /compact Keep the implementation approach, summarize exploration
  2. Put important persistent information in your CLAUDE.md file
  3. For complex tasks, break into shorter sessions

File and Configuration Problems

Claude isn't reading my CLAUDE.md file

The file might be named wrong or in the wrong location.

Solution

  1. Check the filename is exactly CLAUDE.md (case-sensitive)
  2. Verify location: project root or ~/.claude/CLAUDE.md
  3. Run /memory to see what files Claude has loaded
  4. Restart Claude Code after creating the file

Claude ignores instructions in my CLAUDE.md

The file might be too long, causing important instructions to get lost.

Solution

  1. Shorten your CLAUDE.md—aim for 1-2 screens max
  2. Put the most important instructions at the top
  3. Use emphasis: ALL CAPS or "IMPORTANT:" for critical rules
  4. Remove anything Claude would do anyway

My custom slash command or skill doesn't appear

The skill might be in the wrong location or named incorrectly. Note that the older .claude/commands/ system has been merged into skills.

Solution

  1. For skills: verify folder structure is .claude/skills/skill-name/SKILL.md (project-level) or ~/.claude/skills/skill-name/SKILL.md (global)
  2. For legacy commands: files should be in .claude/commands/ (they still work)
  3. Folder name must be lowercase with hyphens (no spaces)
  4. Run /help to see all available commands including custom ones
  5. Restart Claude Code to pick up new skills

MCP server not connecting

Model Context Protocol (MCP) servers extend Claude Code with external tools and data sources, but connection issues are common.

Solution

  1. Run Claude Code with --mcp-debug flag for detailed MCP diagnostics
  2. Check your MCP server configuration in .claude/settings.json
  3. Verify the MCP server process is running and accessible
  4. Check that the server URL and authentication are correct
  5. Try restarting both the MCP server and Claude Code

Permission Problems

Claude keeps asking permission for everything

This is the default safety behavior. You can change it.

Solution

  1. Press Shift+Tab to enter Auto-Accept Mode
  2. Or configure trusted directories in settings
  3. Run /config to open settings

Claude won't edit files / is in read-only mode

You might be in Plan Mode, which is read-only.

Solution

  1. Check if "plan mode on" appears in your terminal
  2. Press Shift+Tab to cycle back to Normal Mode
  3. If using CLI flags, remove --permission-mode plan

Connection Problems

"Network error" or "Connection failed"

Claude Code can't reach Anthropic's servers.

Solution

  1. Check your internet connection
  2. If using VPN, try disabling it temporarily
  3. Check status.anthropic.com for outages
  4. If behind corporate firewall, you may need proxy configuration

Diagnostic Commands

Use these commands to diagnose issues:

Command What It Shows
claude doctor Full health check of your installation (run from terminal)
/status Version, model, account info
/memory Which CLAUDE.md files are loaded
/cost Token usage and costs for current session
/usage Rate limits and plan usage
/model Current model and option to switch (Opus 4.6, Sonnet 4.5, Haiku 4.5)
/help All available commands including custom skills

For deeper debugging, you can also use these terminal flags:

Model-Specific Issues

Getting unexpected results or lower quality output

You might be using a less capable model for a complex task.

Solution

  1. Check which model you're using: /model
  2. For complex tasks, switch to Sonnet 4.5 or Opus 4.6: /model sonnet or /model opus
  3. Haiku 4.5 is fast and cheap but less capable for complex reasoning
  4. Break complex tasks into smaller steps if using a lighter model

Still Not Working?

If none of these solutions helped:

  1. Update Claude Code: npm update -g @anthropic-ai/claude-code
  2. Check for known issues: GitHub Issues
  3. Check Anthropic status: status.anthropic.com for service outages
  4. Report a bug: If you found a new issue, report it on GitHub

When reporting issues: Include the output of claude doctor and /status, your operating system, Node.js version, and the exact error message you're seeing.

Related Guides

Like Claude Code? Meet Your Chief AI Officer

Once you've fixed the issue, watch our free training to see Claude Code in action.

Get the Free Blueprint href="/blueprint">Watch the Free Setup Video →rarr;