Section 02: Troubleshooting & Common Issues

Quick Navigation:

• Troubleshooting Decision Tree ← Start here when stuck
• Authentication Issues
• Extended Thinking Issues
• Context Window Problems
• Performance Problems
• Cost Problems
• VS Code Extension Issues

---

Troubleshooting Decision Tree

Start here when something isn’t working.

Quick Decision Guide

Problem → Diagnosis → Solution

1. Not responding? → Check API Key
2. Poor quality? → Add Context
3. Too slow? → Reduce Context Size
4. High costs? → Enable Caching
5. Extension issues? → Check VS Code Version

If Claude runs but results are poor or inconsistent → Anti-Patterns. Reviewing AI-generated code → PR Review Guide.

---

Decision Tree

Problem 1: Claude Not Responding At All

Symptoms:

• Command hangs
• No output
• Connection timeout
• 401/403 errors

Quick Fixes:

1. Check API Key

   echo $ANTHROPIC_API_KEY  # Should start with sk-ant-
   export ANTHROPIC_API_KEY="your-key"  # If missing
   

2. Test Connection

   curl -I https://api.anthropic.com  # Should return 200
   

3. Check Service Status
   • Visit: https://status.anthropic.com/
4. Verify Installation

   claude --version  # Should show version
   # If missing, reinstall:
   curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
   # Or: irm https://claude.ai/install.ps1 | iex  # Windows PowerShell
   

5. Debug Mode

   claude "test" --debug --verbose
   

Common Fixes:

• Missing key → export ANTHROPIC_API_KEY="sk-ant-..."
• Expired key → Generate new at console.anthropic.com
• Network issue → Check firewall/proxy
• Version conflict → Reinstall: curl -fsSL https://claude.ai/install.sh | bash

---

Problem 2: Response Quality Poor

Symptoms:

• Generic answers
• Missing context
• Incorrect solutions
• Hallucinations

Decision Path:

Question A: Is prompt specific enough?

❌ Vague prompt:

claude "fix my code"

✅ Specific prompt:

claude "Fix authentication error on line 45 of src/auth.ts - 
users can't log in after OAuth callback. Error: 'session undefined'.

@src/auth.ts
@src/middleware/session.ts

Steps to reproduce:
1. Click 'Login with Google'
2. Authorize on Google
3. Redirect to /callback
4. Error thrown

Expected: User logged in
Actual: 500 error, session undefined"

Improvement checklist:

• Specific problem described
• Relevant files attached
• Error messages included
• Steps to reproduce provided
• Expected vs actual behavior stated

Question B: Is context sufficient?

❌ Insufficient context:

claude "why is auth failing?"

✅ Sufficient context:

claude "why is auth failing?

Context:
@src/auth/validate.ts
@src/middleware/auth.ts
@config/database.ts

Error log:
[paste full error]

System:
- Node.js 20
- PostgreSQL 15
- Redis 7
- 1000 req/min traffic

Recent changes:
- Added OAuth yesterday
- Database migrated this morning"

Context checklist:

• All relevant files attached
• Full error messages (not truncated)
• System information
• Recent changes noted
• Scale/traffic info (if performance issue)

Question C: Need deeper reasoning?

For complex problems:

# Enable extended thinking
claude --thinking=5000 "complex architectural question"

# Use Opus 4.5 for hardest problems (opus alias = current flagship; see [Model configuration](https://code.claude.com/docs/en/model-config))
claude --model opus "difficult debugging"

When to use extended thinking:

• ✅ Complex architecture decisions
• ✅ Multi-step debugging
• ✅ System design
• ❌ Simple questions
• ❌ Code formatting
• ❌ Quick reviews

---

Problem 3: Too Slow

Symptoms:

• Responses take 10+ seconds
• Extension freezes
• Timeouts

Decision Path:

Question A: Using extended thinking unnecessarily?

Check your command:

# ❌ Slow: Extended thinking for simple task
claude --thinking=10000 "add comment to function"

# ✅ Fast: No thinking needed
claude "add comment to function"

Fix: Remove --thinking flag for simple tasks

Question B: Context too large?

# ❌ Slow: Attached 100+ files
claude "explain auth" @src/**/*.ts

# ✅ Fast: Specific files only
claude "explain auth" @src/auth/validate.ts @src/middleware/auth.ts

Fix:

1. Use codebase search first: claude "find auth validation code"
2. Then read specific files
3. Attach only 3-5 most relevant files

Question C: Wrong model?

# ❌ Slow: Opus for simple task
claude --model opus "format code"

# ✅ Fast: Haiku for simple task
claude --model claude-haiku-4-5 "format code"

Model selection:

• Simple tasks → Haiku (10x faster)
• Daily coding → Sonnet (balanced)
• Complex problems → Opus (thorough but slow)

Question D: Streaming disabled?

# ❌ Feels slow: Wait for full response
claude "explain" --no-stream

# ✅ Feels fast: Incremental output
claude "explain" --stream

Fix: Enable streaming (default in most cases)

Performance optimization checklist:

• Extended thinking only for complex tasks
• Context limited to 3-5 relevant files
• Using appropriate model (Haiku for simple)
• Streaming enabled
• Prompt caching enabled (create CLAUDE.md)

---

Problem 4: Costs Too High

Symptoms:

• Monthly bill higher than expected
• Token usage surprisingly high
• Budget alerts triggering

Decision Path:

Step 1: Check Usage Stats

# See current month usage
claude --usage-stats --month=current

# See by operation type
claude --cost-report --sort-by=cost --top=20

# Example output:
# Operation                    Cost    Tokens
# git-diff-review              $5.20   520K
# extended-thinking-arch       $3.40   45K
# file-generation              $2.10   210K

Step 2: Identify Cost Drivers

Common culprits:

A. No Prompt Caching (90% more expensive)

# Check if CLAUDE.md exists
ls CLAUDE.md

# If missing, create it:
cat > CLAUDE.md << 'EOF'
# Project: [Your Project Name]

## Tech Stack
[Your stack]

## Architecture
[Your architecture]

## Conventions
[Your conventions]
EOF

Savings: 90% on repeated context

B. Using Wrong Model

# Check default model
claude --config-get defaultModel

# If it's Opus, change to Sonnet/Haiku:
claude --config-set defaultModel claude-sonnet-4-5

Savings: 5-10x depending on model switch

C. Extended Thinking Always On

# Check if thinking is enabled in settings
cat ~/.claude/settings.json | grep thinking

# Configure via settings.json or /config command

Use thinking only explicitly:

claude --thinking=5000 "complex task"

Savings: 2-3x for tasks that don’t need it

D. Not Using Batch API

# ❌ Expensive: Process 100 files synchronously
for file in *.ts; do
  claude "process $file"
done

# ✅ Cheaper: Use Batch API (50% discount)
claude --batch files.txt

Savings: 50% for async work

Step 3: Set Budget Alerts

# Set monthly budget
claude --set-budget 100  # $100/month

# Alert at 80%
claude --alert-at 80

# Get notifications
claude --notify-email your@email.com

Cost optimization checklist:

• CLAUDE.md exists (enables caching)
• Default model is Sonnet/Haiku (not Opus)
• Extended thinking disabled by default
• Using Batch API for async work
• Budget alerts configured

Target costs:

• Individual developer: $5-10/month (optimized)
• Heavy user: $20-50/month
• Team of 10: $50-200/month (optimized)

See Section 15: Cost Optimization for detailed strategies.

---

Problem 5: VS Code Extension Issues

Symptom A: Extension Not Loading

Step 1: Check Installation

# List installed extensions
code --list-extensions | grep anthropic

# Expected: anthropic.claude-code
# If missing:
code --install-extension anthropic.claude-code

Step 2: Check VS Code Version

Help → About → Version

Required: 1.98.0 or higher

If older: Update VS Code

Step 3: Reload Window

Cmd/Ctrl+Shift+P → "Reload Window"

Step 4: Check Extension Logs

View → Output → Select "Claude Code" dropdown

Look for errors in red.

Symptom B: Plan Mode Not Showing

Cause 1: Disabled in Settings

// Settings → Claude Code → Plan Mode
{
  "claudeCode.planMode": true  // Must be true
}

Cause 2: Single-File Change Plan Mode only activates for multi-file changes or large refactorings.

Force Plan Mode:

User: "Create a plan to refactor X - don't apply yet"

Symptom C: Slow Performance

Fix 1: Close Old Sessions

• Click session list
• Close completed conversations
• Keep only active ones

Fix 2: Detach Large Files

• Click “X” on attached files when done
• Only attach 3-5 files at a time

Fix 3: Restart Extension

Cmd/Ctrl+Shift+P → "Reload Window"

Symptom D: API Key Not Working

Step 1: Check Key in Settings

Settings → Search "Claude Code" → API Key

Verify key is correct (starts with sk-ant-)

Step 2: Check Environment Variable

echo $ANTHROPIC_API_KEY

Extension uses environment variable if setting is empty.

Step 3: Generate New Key

• Go to console.anthropic.com
• Create new API key
• Update in VS Code settings
• Reload window

See Section 3: VS Code Extension Guide for comprehensive extension troubleshooting.

---

Problem 6: Merge Conflicts

Symptom: Git merge conflicts with Claude-generated code

Decision Path:

Step 1: List Conflicts

git diff --name-only --diff-filter=U

Step 2: Use Claude to Resolve

# Get full conflict context
git diff > conflicts.txt

# Ask Claude
cat conflicts.txt | claude "Help resolve these merge conflicts:

For each file in conflict:
1. What changed in each branch
2. How to merge both changes
3. Potential issues after merge
4. Resolved code

Be conservative - prefer keeping both changes unless they're contradictory."

Step 3: Apply Resolutions

• Review Claude’s suggested resolutions
• Apply to files manually
• Test thoroughly

Step 4: Mark Resolved

git add <resolved-files>
git merge --continue

Prevention:

• Pull frequently (daily)
• Coordinate with team on shared files
• Use feature branches
• Small, frequent commits

---

Quick Fixes Reference Table

Symptom	Most Likely Cause	Quick Fix
“Command not found”	CLI not installed	curl https://claude.ai/install.sh \| bash
“Invalid API key”	Key not set or expired	export ANTHROPIC_API_KEY="your-key"
Very slow responses	Extended thinking on	Remove --thinking flag
High costs	No prompt caching	Create CLAUDE.md file
Generic answers	Insufficient context	Attach relevant files with @file
Extension not loading	Old VS Code version	Update VS Code to 1.98.0+
Context window exceeded	Too many files	Attach only 3-5 relevant files
Plan Mode not showing	Single file change	Request multi-file change or “create plan”
Rate limited (429)	Too many requests	Wait or upgrade plan
Connection timeout	Network/firewall issue	Check firewall, try different network

---

When to Ask for Help

Try self-troubleshooting first using this decision tree.

Ask for help if:

• ✅ Followed decision tree completely
• ✅ Checked all quick fixes
• ✅ Problem persists for 30+ minutes
• ✅ Impacts production system
• ✅ Potential bug in Claude Code itself

Where to ask:

1. Anthropic Discord → anthropic.com/discord (most active)
2. GitHub Issues → For confirmed bugs
3. Email Support → For account/billing issues

What to include in help request:

**Problem:** [One sentence description]

**What I tried:**
1. [Step from decision tree]
2. [Another step]
3. [etc.]

**Environment:**
- OS: [Windows/Mac/Linux]
- VS Code version: [if using extension]
- Claude CLI version: [run `claude --version`]
- Node version: [run `node --version`]

**Error logs:**
[Paste relevant logs]

**To reproduce:**
1. [Step 1]
2. [Step 2]
3. [See error]

---

Authentication Issues

API Key Not Recognized

# Check environment variable
echo $ANTHROPIC_API_KEY

# If empty, set it
export ANTHROPIC_API_KEY="sk-ant-your-key"

# Test
claude "test"

MCP Configuration Issues

MCP (Model Context Protocol) server issues are common but usually easy to diagnose and fix.

Problem: Authentication Failures

Symptoms: “MCP server authentication failed”, “401 Unauthorized”, “403 Forbidden”

Diagnosis:

# Check environment variables are set
echo $GITHUB_TOKEN  # macOS/Linux
echo $env:GITHUB_TOKEN  # Windows PowerShell

# Verify variable in config
claude mcp get github | grep TOKEN

# Check MCP config files
cat ~/.claude.json      # User-level config
cat .mcp.json          # Project-level config

Solution:

# Ensure environment variable is set
export GITHUB_TOKEN="ghp_your_token"  # macOS/Linux
$env:GITHUB_TOKEN = "ghp_your_token"  # Windows

# Re-add server with correct token
claude mcp remove github
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --env GITHUB_TOKEN="${GITHUB_TOKEN}"

# Test connection
claude mcp test github

Problem: Transport-Specific Issues

HTTP Transport Issues:

# Timeout errors - check URL is reachable
curl https://api.example.com/mcp/
# Should return MCP server metadata

# 401/403 errors - verify authentication
claude mcp get <name> | grep -i auth
# Check headers and tokens are correct

# SSL certificate errors
# MCP validates HTTPS certificates by default
# If using self-signed certs, contact your admin

Stdio Transport Issues:

# "Command not found" - verify npx/node is in PATH
which npx  # macOS/Linux
where npx  # Windows

# Process crashes - check server logs
claude mcp test <name> --verbose
# Shows full error output

# Common issue: Missing dependencies
npm install -g npx  # Ensure npx is available

Windows Stdio Issues:

# Windows requires cmd /c wrapper
# Incorrect (will fail):
claude mcp add --transport stdio gdrive -- npx -y @mcp/server-gdrive

# Correct (with cmd /c):
claude mcp add --transport stdio gdrive -- cmd /c npx -y @mcp/server-gdrive

# Verify Node.js is in PATH
where.exe node
where.exe npx

Problem: Scope Conflicts

Symptoms: Server not available in some projects, “MCP server not found”

Diagnosis:

# Check which scope the server is in
claude mcp list
# Shows: Name | Transport | Scope | Status

# Verify server exists
claude mcp get <server-name>
# Shows full configuration including scope

Solution:

# Add to correct scope for your use case

# Local scope - personal, this project only
claude mcp add --scope local custom-api ...

# Project scope - team-shared, in .mcp.json
claude mcp add --scope project jira ...
git add .mcp.json  # Commit for team

# User scope - personal, all projects
claude mcp add --scope user gdrive ...

# Check servers available in current project
cd /path/to/project
claude mcp list

Scope Hierarchy (highest to lowest priority):

1. Local (~/.claude.json in project dir)
2. Project (.mcp.json in project root)
3. User (~/.claude.json in home dir)
4. Managed (system-wide paths)

Problem: Environment Variable Expansion Not Working

Symptoms: “Environment variable not set”, credentials not loading

Diagnosis:

# Check if variable is set
echo $MY_TOKEN  # macOS/Linux
echo $env:MY_TOKEN  # Windows

# Check configuration syntax
claude mcp get <name>
# Look for ${VAR} syntax

Common Mistakes:

# Incorrect: Variable not set
claude mcp add --env TOKEN="${UNDEFINED_VAR}"
# Error: "Environment variable UNDEFINED_VAR not set"

# Incorrect: Wrong syntax (no $ or braces)
claude mcp add --env TOKEN="GITHUB_TOKEN"
# Treats literal string "GITHUB_TOKEN" as value

# Incorrect: Single quotes prevent expansion in shell
export TOKEN='${GITHUB_TOKEN}'  # Wrong

Correct Usage:

# Set variable first
export MY_TOKEN="actual_token_value"

# Reference in config
claude mcp add --env TOKEN="${MY_TOKEN}"

# Use default value if variable might not be set
claude mcp add --env TOKEN="${MY_TOKEN:-default_value}"

# Use required variable (fails if not set)
claude mcp add --env TOKEN="${MY_TOKEN}"

Environment Variable Expansion Syntax:

• ${VAR} - Required variable (fails if not set)
• ${VAR:-default} - Optional variable with default value

Problem: Windows-Specific Issues

Path Separator Errors:

# Incorrect: Backslashes in URLs
claude mcp add --transport http api https:\\api.example.com\mcp

# Correct: Always use forward slashes in URLs
claude mcp add --transport http api https://api.example.com/mcp

# File paths: Forward slashes work on Windows too
--cwd C:/Users/name/project  # Recommended
--cwd C:\Users\name\project  # Also works but escape backslashes

npx Not Found:

# Check if Node.js/npx is installed
where.exe node
where.exe npx

# If not found, install Node.js, then verify
node --version
npx --version

# After installing, use cmd /c wrapper
claude mcp add --transport stdio server -- cmd /c npx -y package

Permission Denied:

# Solution 1: Run PowerShell as Administrator
# Right-click PowerShell → "Run as Administrator"

# Solution 2: Check execution policy
Get-ExecutionPolicy
# If "Restricted", set to RemoteSigned:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Environment Variables in PowerShell:

# Temporary (current session only)
$env:GITHUB_TOKEN = "ghp_token"

# Permanent (user level)
[System.Environment]::SetEnvironmentVariable(
    'GITHUB_TOKEN',
    'ghp_token',
    'User'
)

# Verify variable is set
echo $env:GITHUB_TOKEN

Diagnostic Commands

# Check MCP server status
claude mcp list
# Shows all servers with status (Connected/Error)

# Test specific server with verbose output
claude mcp test <server-name> --verbose
# Shows detailed connection info, errors, timing

# Get server configuration
claude mcp get <server-name>
# Shows command, args, env, transport, scope

# Within Claude session, run full diagnostics
claude
> /doctor
# Checks:
# - Authentication status
# - MCP server connections
# - Environment variables
# - Configuration validation
# - Common issues

Quick Fixes Reference

Problem	Quick Fix
Auth fails	Check echo $ENV_VAR is set, re-add server with claude mcp remove then claude mcp add
Server not found	Check scope with claude mcp list, ensure correct scope for your use case
Windows npx error	Use -- cmd /c npx -y package wrapper for stdio servers
Connection timeout	Verify URL is reachable with curl <url>, check network/firewall
Variable not expanding	Use ${VAR:-default} syntax, verify variable is exported
Permission denied	Run PowerShell as Administrator, check file permissions
Stdio server crashes	Run claude mcp test <name> --verbose to see error details
Wrong scope	Add server with --scope user\|project\|local flag

Advanced MCP Troubleshooting

Enable Debug Logging:

# Set debug environment variable
export CLAUDE_DEBUG=1  # macOS/Linux
$env:CLAUDE_DEBUG = "1"  # Windows

# Run command with debug output
claude mcp test <name>

Check MCP Server Logs:

# Server logs location (varies by transport)
# Stdio servers: Check terminal output
claude mcp test <name> --verbose

# HTTP servers: Check server-side logs
curl -v https://api.example.com/mcp/

Test MCP Server Directly:

# Test stdio server outside of Claude
npx -y @modelcontextprotocol/server-gdrive

# Test HTTP server with curl
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/mcp/

# Verify server responds with MCP protocol

Reset MCP Configuration:

# Remove all local-scope servers
rm ~/.claude.json  # Backup first!

# Reset project MCP choices
claude mcp reset-project-choices

# Re-add servers one by one
claude mcp add --scope user gdrive ...

Getting Help

If issues persist after troubleshooting:

1. Check Configuration:

   claude mcp list
   claude mcp get <problem-server>
   

2. Test Connections:

   claude mcp test <server-name> --verbose
   

3. Run Diagnostics:

   claude
   > /doctor
   

4. Gather Information:
   • MCP server name and transport type
   • Error messages (exact text)
   • Output of claude mcp get <name>
   • Operating system and version
   • Claude Code version (claude --version)
5. Report Issue:
   • Visit: https://github.com/anthropics/claude-code/issues
   • Include diagnostic information
   • Attach error logs (remove sensitive data)

Extended Thinking Issues

Timeout on Large Budgets

Problem: Requests with 32K+ thinking budget timeout

Solution:

• Use Batch API for >32K budgets
• Start with 10K, increase if needed
• Break complex tasks into steps

Unexpected Costs

Problem: Extended thinking more expensive than expected

Solution:

• Start with 2K budget
• Monitor token usage
• Use thinking only for complex tasks
• Consider Claude Haiku 4.5 for simple tasks

Context Window Overflow

Too Many Files

Problem: “Context window exceeded” error

Solution:

# Use focused context
claude "@specific-file" instead of "@entire-directory"

# Configure ignore patterns in .claude/settings.json
# Or add to project .gitignore (Claude respects .gitignore)

# Use Batch API for full codebase analysis

Performance Issues

Slow Responses

Problem: Claude takes too long to respond

Solutions:

1. Use faster model (Claude Haiku 4.5)
2. Reduce context (fewer files)
3. Disable extended thinking for simple tasks
4. Use streaming for immediate feedback

High API Costs

Problem: Unexpected high bills

Solutions:

1. Enable prompt caching (90% savings)
2. Use Claude Haiku 4.5 for simple tasks
3. Set monthly budget limits
4. Monitor usage dashboard

CLI Installation Issues

Command Not Found

# Add to PATH
export PATH="$HOME/.claude/bin:$PATH"

# Or reinstall
curl -fsSL https://claude.ai/install.sh | sh

Permission Denied

# Fix permissions
chmod +x ~/.claude/bin/claude

# Or reinstall with proper permissions
curl -fsSL https://claude.ai/install.sh | bash

← Back: Reference Guide

Next: Productivity Metrics →