Troubleshooting

Diagnose and fix common issues with Claude Code.

Run diagnostics first

The /doctor command runs a comprehensive set of checks on your installation and configuration:

/doctor

It checks your install method, shell PATH, Node.js version, API connectivity, ripgrep availability, sandbox status, and more. Review its output before digging into individual issues.

Authentication issues

API key not recognized

Claude Code looks for your API key in this order:

1. ANTHROPIC_API_KEY environment variable
2. Keychain / credential store (set via /login)
3. Project or user settings

Fix: Run /login to re-authenticate, or export the key in your shell:

export ANTHROPIC_API_KEY=sk-ant-...

Verify it’s set:

echo $ANTHROPIC_API_KEY

Login fails or OAuth error

If the browser-based OAuth flow fails:

• Make sure you have an active claude.ai or Anthropic Console account
• Try /logout then /login to restart the flow
• As a fallback, set ANTHROPIC_API_KEY directly in your shell environment

403 or 401 errors from the API

These indicate the key is present but invalid or expired.

• Rotate your API key in the Anthropic Console
• Re-run /login or update the ANTHROPIC_API_KEY env var
• Check that ANTHROPIC_BASE_URL is not set to an incorrect endpoint

Installation problems

'claude' command not found after install

Your shell’s PATH may not include the npm global bin directory.

Find where npm installs global binaries:

npm bin -g

Add that path to your shell config (~/.bashrc, ~/.zshrc, or ~/.profile):

export PATH="$(npm bin -g):$PATH"

Reload your shell:

source ~/.zshrc  # or ~/.bashrc

Node.js version too old

Claude Code requires a recent version of Node.js. Check your version:

node --version

If it’s below v18, upgrade Node.js using your package manager or nvm:

nvm install --lts
nvm use --lts

Native installer lock file error

If you see a message about a lock file or in-progress installation, another install may be running. Wait a moment and retry. If the issue persists, remove the lock file manually:

rm ~/.local/share/claude-code/.install-lock 2>/dev/null || true

Then re-run the install command.

Permission denied during install

Avoid using sudo with npm. Instead, configure npm to use a user-owned directory:

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

Then install again without sudo:

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

Performance issues

Responses are slow

• Check your network connection and API status
• Large context windows slow down responses — use /compact to summarize the conversation
• Use /effort to reduce reasoning effort for simple tasks:
  /effort low
  
• Use /fast to switch to a faster model for the current session

Context window full errors

Claude Code has a finite context window. When it fills up:

• Use /compact to compress the conversation history into a summary
• Start a fresh session with /clear for unrelated tasks
• Use /add-dir sparingly — avoid adding large directories unnecessarily

High token costs

• Use /cost to see token usage for the current session
• Use /usage for a summary of recent spending
• Use /effort low for straightforward tasks
• Avoid repeatedly reading large files — Claude caches file reads within a session

IDE integration issues

IDE extension not connecting

Run /ide to check the current IDE connection status and attempt reconnection.

Make sure the Claude Code extension is installed in your IDE:

• VS Code: Install “Claude Code” from the Extensions marketplace
• JetBrains: Install “Claude Code” from the JetBrains Plugin Marketplace

Restart your IDE after installing the extension.

Diffs not showing in IDE

The diff view requires the IDE extension to be connected. If /ide shows no connection:

1. Open your IDE with the current project
2. Ensure the Claude Code extension is enabled
3. Run /ide again inside Claude Code

MCP server issues

MCP server fails to connect

Check the server configuration in your settings:

/mcp

Common causes:

• Wrong command path: Ensure the command in your MCP config is a valid executable on your PATH
• Missing dependencies: The MCP server process may require its own dependencies installed
• Environment variables: Some MCP servers need env vars (set them in the env config field)

Check the MCP server logs — Claude Code outputs connection errors to the terminal on startup.

MCP tools not appearing

After adding a new MCP server, restart Claude Code. MCP connections are initialized on startup.

Verify the server is listed and enabled:

/mcp

If it shows as disabled, toggle it on with the interactive menu.

Tool permission issues

Claude keeps asking permission for the same tool

To permanently allow a tool, respond with “Always allow” when the permission prompt appears. This adds the tool to your allowedTools list in settings.

You can also add it manually in your settings file or via /permissions.

Tool was denied and now Claude won't use it

If you accidentally denied a tool permanently, reset it via /permissions or edit your settings file to remove the denial rule.

Keeping Claude Code up to date

Run the upgrade command inside Claude Code:

/upgrade

Or update via npm:

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

Check the current version:

claude --version

Enable debug logging

For deep troubleshooting, use the --debug flag when starting Claude Code, or set the DEBUG environment variable:

claude --debug
# or
DEBUG=1 claude

This writes detailed logs to ~/.claude/logs/, including tool calls, API requests, and internal state. You can also set CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose for even more detailed output.

If you’re still stuck, use /feedback inside Claude Code to send a report directly to the team.