Lesson 17: Troubleshooting

When something goes wrong with Claude Code, you want answers fast. This lesson is organized as a "when X happens, do Y" reference. Start with /doctor — the built-in diagnostic command — then find your specific issue below.

First Step: Run /doctor

The /doctor command is your single most useful troubleshooting tool. Run it first, every time. It checks your entire Claude Code setup in seconds:

> /doctor

What /doctor inspects:

• Installation — type, version, and whether the claude binary is on your PATH
• Auto-update — whether updates are working and what versions are available
• Search — whether ripgrep is installed and functional
• Settings files — malformed JSON, incorrect types, invalid values
• MCP servers — configuration errors and connection problems
• Keybindings — configuration issues that prevent shortcuts from working
• Context — large CLAUDE.md files, high MCP token usage, unreachable permission rules
• Plugins and agents — loading errors in custom extensions

If /doctor reports a problem, fix that first before investigating further. Most issues show up here.

Common Installation Issues

The `claude` Command Is Not Found

Symptom: You installed Claude Code but typing claude gives "command not found."

Fix (npm install):

# Check where npm installed it
npm list -g @anthropic-ai/claude-code

# Ensure npm's global bin is on your PATH
npm config get prefix
# Add <prefix>/bin to your PATH

Fix (native install): The native installer puts the binary at ~/.local/bin/claude. Make sure that directory is in your PATH.

On macOS/Linux, add to your shell config (~/.bashrc, ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

On Windows, add %USERPROFILE%\.local\bin to your User PATH through System Properties > Environment Variables.

Native Installer Option

If npm is giving you trouble, skip it entirely and use the native installer:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

This installs a standalone build that does not depend on npm or Node.js.

Permission Errors During npm Install

Symptom: EACCES errors when running npm install -g.

Fix: Never use sudo with npm. Instead, fix npm's global prefix:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to your shell config:
export PATH="$HOME/.npm-global/bin:$PATH"

Then reinstall:

npm install -g @anthropic-ai/claude-code

Windows-Specific Troubleshooting

Claude Code on Windows requires Git Bash (included with Git for Windows). This section covers the common Windows issues.

"Claude Code on Windows requires git-bash"

Symptom: Claude Code refuses to start, saying it needs Git Bash.

Fix:

1. Install Git for Windows if you have not already
2. If Git is installed but not detected, set the path explicitly in PowerShell:

$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

To make this permanent, add CLAUDE_CODE_GIT_BASH_PATH as a system environment variable through System Properties > Environment Variables.

"installMethod is native, but claude command not found"

Symptom: The native installer completed but claude is not recognized.

Fix:

1. Press Win+R, type sysdm.cpl, press Enter
2. Click Advanced > Environment Variables
3. Under "User variables", select Path and click Edit
4. Click New and add: %USERPROFILE%\.local\bin
5. Close and reopen your terminal

Verify with:

claude doctor

WSL Installation Issues

OS/platform detection errors:

# If WSL is using Windows npm instead of Linux npm
npm config set os linux
npm install -g @anthropic-ai/claude-code --force --no-os-check

Node not found errors: Check that which npm and which node point to Linux paths (starting with /usr/) not Windows paths (starting with /mnt/c/). If they point to Windows paths, install Node via your Linux distro's package manager or via nvm.

nvm version conflicts between WSL and Windows: WSL imports the Windows PATH by default, so Windows nvm/npm can take priority. Fix by ensuring nvm is loaded in your shell config:

# Add to ~/.bashrc or ~/.zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

WSL Sandbox Setup

If you see "Sandbox requires socat and bubblewrap":

# Ubuntu/Debian
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

Note: WSL1 does not support sandboxing. You need WSL2 for sandbox features.

Slow Search Results on WSL

Working across file systems on WSL has performance penalties. If searches return fewer results than expected:

1. Be more specific — specify directories or file types in your prompts
2. Move your project to the Linux filesystem — /home/ performs much better than /mnt/c/
3. Consider running natively on Windows instead of through WSL

Authentication Problems

Token Expired or Login Fails

Symptom: Claude Code cannot authenticate, shows token errors, or the login flow does not complete.

Fix (standard):

1. Run /logout inside Claude Code
2. Close Claude Code
3. Restart with claude and complete the login flow again

If the browser does not open automatically during login, press c to copy the OAuth URL to your clipboard and paste it into your browser.

Fix (nuclear option): If the above does not work, remove the stored auth data entirely:

rm -rf ~/.config/claude-code/auth.json
claude

This forces a completely clean login.

Switching Between Accounts or Organizations

If you need to switch from one Anthropic account to another:

1. Run /logout
2. Restart claude
3. Log in with the other account

API Key Authentication

If you are using an API key instead of OAuth:

export ANTHROPIC_API_KEY=your-key-here
claude

Check that the key is valid, has not been revoked, and has sufficient permissions for the model you are trying to use.

Performance Issues

Slow Responses

Possible causes and fixes:

1. Context too large — Use /compact to reduce context size (see below)
2. Large repo — Claude may be scanning too many files. Add large build directories to .gitignore
3. Model overload — Peak usage times can slow responses. Try again in a few minutes
4. Network — Check your internet connection and proxy settings (see Network Issues below)

High Memory or CPU Usage

Claude Code can consume significant resources when processing large codebases.

Fix:

1. Use /compact regularly to reduce the in-memory context
2. Close and restart Claude Code between major tasks
3. Ensure large generated directories (node_modules, dist, build, .next) are in .gitignore

Search Not Working or Missing Results

If the Search tool, @file mentions, custom agents, or custom skills are not working:

# macOS
brew install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Arch Linux
pacman -S ripgrep

Then set the environment variable:

export USE_BUILTIN_RIPGREP=0

The /rewind Command

When Claude makes a change you did not want, /rewind lets you undo it — both the conversation and the code changes.

> /rewind

You can also press Esc twice to trigger the rewind/summarize interface.

What /rewind does:

• Shows you a list of recent conversation turns
• Lets you select a point to rewind to
• Restores your code to the state it was in at that point
• Rolls back the conversation so Claude "forgets" everything after that point

When to use /rewind:

• Claude edited the wrong file
• Claude went down a bad implementation path
• You want to try a different approach from a specific point
• Claude made changes that broke something and you want a clean slate

Rewind vs. git checkout: /rewind rolls back both the conversation and file changes. git checkout . only reverts files — Claude still "remembers" the bad approach and may repeat it.

The /compact Command

When your conversation gets long, Claude starts losing track of earlier context. The /compact command summarizes the conversation to free up space.

> /compact

You can also give it focus instructions:

> /compact focus on the authentication changes we discussed

When to use /compact:

• Claude forgets something you discussed earlier in the session
• Responses are getting slower (large context = slower processing)
• You are switching to a different subtask within the same session
• Claude starts repeating itself or asking questions you already answered

How it works: Claude summarizes the conversation into a condensed form, preserving the key decisions and context while discarding the back-and-forth. This frees up context window space for new work.

Tip: If you find yourself compacting frequently, consider starting a new session instead. Use /compact for mid-task context management; use a new session for switching to an entirely different task.

Permission Issues

Repeated Permission Prompts

Symptom: Claude keeps asking for permission to run the same commands.

Fix: Use /permissions to allow specific tools to run without approval:

> /permissions

This opens an interface where you can add allow rules for tools you trust, like:

• Bash(npm test) — allow running tests
• Bash(git *) — allow all git commands
• Read — allow reading files without prompts

Settings Conflicts

Claude Code reads settings from multiple files in a specific order:

If permissions behave unexpectedly, check all three files. Project settings can override your user settings. The /doctor command also flags unreachable permission rules.

Sandbox Problems

If sandboxing is preventing legitimate operations:

• Run /status to check your current sandbox mode
• On macOS, sandboxing uses Apple's Seatbelt; on Linux, it uses bubblewrap
• On WSL2, install bubblewrap and socat (see WSL section above)
• WSL1 does not support sandboxing

MCP Server Issues

MCP Server Not Connecting

Symptom: You configured an MCP server but Claude cannot use its tools.

Diagnosis checklist:

1. Run /doctor — it checks MCP configuration automatically
2. Run /mcp to see the status of all configured servers
3. Check that the server is listed in the right config file:

Common fixes:

# Test the server manually
npx -y @modelcontextprotocol/server-github

# Check environment variables are set
echo $GITHUB_TOKEN

MCP Server Crashes or Timeouts

• Restart Claude Code after changing MCP configuration
• Use absolute paths in server commands
• Check that required environment variables (API keys, tokens) are set
• Look at server logs for specific error messages
• Keep credentials in environment variables, not in settings files

Debugging MCP with Verbose Mode

For detailed MCP diagnostics, start Claude Code in debug mode:

claude --debug "mcp"

This shows the full communication between Claude Code and your MCP servers.

Network Issues

Proxy Configuration

If you are behind a corporate proxy:

export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080
claude

Firewall Blocking Connections

Claude Code needs to reach Anthropic's API servers. If your firewall blocks outbound HTTPS:

1. Ensure api.anthropic.com is allowed on port 443
2. Check with your IT department about proxy or firewall exceptions
3. Run /doctor to confirm connectivity

WSL2 Network Issues with IDEs

If Claude Code in WSL2 cannot detect your JetBrains IDE:

Option 1: Configure Windows Firewall (recommended)

# Find your WSL2 IP
wsl hostname -I

# Create a firewall rule (run as Administrator)
New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" `
  -Direction Inbound -Protocol TCP -Action Allow `
  -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

Option 2: Switch to mirrored networking

Add to .wslconfig in your Windows user directory:

[wsl2]
networkingMode=mirrored

Then restart WSL:

wsl --shutdown

Other Useful Diagnostic Commands

Beyond /doctor, Claude Code has several other commands that help with troubleshooting:

Verbose and Debug Modes

For deeper diagnostics, start Claude Code with extra logging:

# Verbose mode — full turn-by-turn output
claude --verbose

# Debug mode — filter by category
claude --debug "api,mcp"
claude --debug "hooks"

Resetting Claude Code

When all else fails, you can reset to a clean state.

Reset user settings and state:

rm ~/.claude.json
rm -rf ~/.claude/

Reset project-specific settings:

rm -rf .claude/
rm .mcp.json

Warning: This removes all your settings, MCP server configurations, permissions, and session history. Use this as a last resort.

A less destructive option is to reset just authentication:

rm -rf ~/.config/claude-code/auth.json
claude

Configuration File Reference

When debugging settings issues, know where Claude Code stores its configuration:

On Windows, ~ refers to your user home directory (e.g., C:\Users\YourName).

Managed settings (set by administrators) are stored in:

• macOS: /Library/Application Support/ClaudeCode/
• Linux/WSL: /etc/claude-code/
• Windows: C:\Program Files\ClaudeCode\

Getting Help

If you are stuck after trying the above:

1. Run /doctor — always start here
2. Run /bug — report the problem directly to Anthropic from within Claude Code
3. Search GitHub Issues — github.com/anthropics/claude-code/issues
4. Ask Claude — Claude has built-in access to its own documentation. Try: "How do I configure proxy settings?" or "Why is my MCP server not connecting?"
5. Check your memory files — sometimes you already solved this problem in a past session:
   Bash

   cat ~/.claude/projects/*/memory/MEMORY.md

Key Takeaways

• Run /doctor first — it catches most problems automatically
• On Windows, Git Bash is required; set CLAUDE_CODE_GIT_BASH_PATH if Git is not on your PATH
• Use /rewind to undo Claude's changes (both code and conversation), not just git checkout
• Use /compact when Claude starts forgetting context or responses slow down
• Authentication issues usually resolve with /logout, restart, and re-login
• Check all three settings files (user, project, local) when permissions behave unexpectedly
• Use claude --debug "mcp" to troubleshoot MCP server connections
• When all else fails, reset your config files and start fresh