Claude Code Troubleshooting

Claude Code is robust, but problems can occur. Here's a complete guide to diagnose and solve the most common errors.

Connection Problems

Error: "API Key invalid"

Error: Invalid API key

Solutions:

1. Verify the key:

echo $ANTHROPIC_API_KEY

2. Reconfigure:

claude config set apiKey sk-ant-...

3. Check permissions on console.anthropic.com

Error: "Rate limit exceeded"

Error: Rate limit exceeded. Please retry after X seconds.

Solutions:

1. Wait for the indicated delay
2. Reduce request frequency
3. Upgrade to a higher plan (Max 20x)
4. Use /compact to reduce tokens

Error: "Connection timeout"

Error: Request timed out

Solutions:

1. Check internet connection
2. Check status: status.anthropic.com
3. Retry with longer timeout:

claude --timeout 120000

Context Problems

Error: "Context window exceeded"

Error: Maximum context length exceeded

Cause: Conversation + files exceed token limit.

Solutions:

1. Use /compact immediately:

/compact

2. Start a new session:

/clear

3. Limit referenced files:

❌ @src/**/*.ts  (too many files)
✅ @src/api/auth.ts  (specific file)

Claude "forgets" instructions

Cause: Context is saturated and old instructions are truncated.

Solutions:

1. Add instructions to CLAUDE.md:

# CLAUDE.md
## Important rule
Always use early returns

2. Repeat critical instructions:

> Reminder: use strict TypeScript.
> Now, implement feature X.

3. Use /compact then reformulate

File not found

Error: File not found: @src/missing.ts

Solutions:

1. Verify the path:

ls src/missing.ts

2. Use correct relative path:

@./src/missing.ts  (with ./)
@src/missing.ts    (without ./)

3. Check read permissions

Execution Problems

Bash command blocked

Claude is waiting for permission...

Solutions:

1. Accept or reject manually
2. Add to permissions:

{
  "permissions": {
    "allow": ["Bash(npm run:*)"]
  }
}

3. Use Accept Edits mode (Shift+Tab)

Error: "Tool not available"

Error: Tool 'WebFetch' is not available

Cause: Tool is disabled or unavailable.

Solutions:

1. Check permissions:

/permissions

2. Enable tool in settings.json

3. Verify tool exists (some are experimental)

Infinite loop

Claude continues endlessly on a task.

Solutions:

1. Interrupt with Ctrl+C
2. Use Esc Esc to go back
3. Reformulate with a limit:

> Do this task in maximum 3 steps

Performance Problems

Very slow responses

Possible causes:

• Context too large
• High server load
• Slow network connection

Solutions:

1. Reduce context:

/compact

2. Limit files:

> Analyze only @src/api/auth.ts

3. Use a faster model:

claude --model haiku

High costs

Diagnosis:

/cost

Solutions:

1. /compact regularly
2. Be more precise in prompts
3. Avoid massive file reads
4. Use Haiku for simple tasks

Installation Problems

npm install fails

npm install -g @anthropic-ai/claude-code
# Error: EACCES permission denied

Solutions:

1. Use npx:

npx @anthropic-ai/claude-code

2. Fix npm permissions:

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

3. Use a Node version manager:

nvm use 20
npm install -g @anthropic-ai/claude-code

Incompatible Node version

Error: Unsupported Node.js version

Solution:

nvm install 18  # or 20
nvm use 18

Hook Problems

Hook doesn't execute

Checks:

1. Hook syntax:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "echo 'Hook triggered'"
      }]
    }]
  }
}

2. Debug logs:

CLAUDE_CODE_DEBUG=1 claude

3. Script permissions:

chmod +x ./scripts/hook.sh

Hook blocks Claude

Hook returned: BLOCK

This is intentional if the hook detects a problem.

Solutions:

1. Check hook conditions
2. Modify the file to satisfy the hook
3. Temporarily disable the hook

MCP Problems

MCP server won't start

Error: Failed to connect to MCP server

Solutions:

1. Verify installation:

npx postgres-mcp-server --version

2. Test manually:

npx postgres-mcp-server

3. Check environment variables:

echo $DATABASE_URL

MCP timeout

Error: MCP server timed out

Solutions:

1. Increase timeout:

{
  "mcpServers": {
    "postgres": {
      "timeout": 30000
    }
  }
}

2. Check network connectivity to the service

General Diagnosis

Debug mode

CLAUDE_CODE_DEBUG=1 claude

Displays detailed logs to identify the problem.

Check configuration

claude config list

Reset configuration

rm -rf ~/.claude
claude config set apiKey sk-ant-...

Check logs

cat ~/.claude/logs/claude-code.log

Troubleshooting Checklist

□ Internet connection OK?
□ API Key valid?
□ Node.js version compatible (≥18)?
□ Claude Code up to date?
□ File permissions OK?
□ Context not saturated?
□ Hooks configured correctly?
□ MCP servers accessible?

Getting Help

Official documentation

/help

Community

• GitHub Issues: github.com/anthropics/claude-code/issues
• Anthropic Discord
• Stack Overflow tag claude-code

Anthropic Support

For Enterprise customers: support.anthropic.com

What's Coming Tomorrow

In Day 18, we'll explore the status line and terminal customization - configure Claude Code display according to your preferences.

This article is part of the "Master Claude Code in 20 Days" series. Day 16: Billing and costs