Claude Code Documentation

Appearance

Troubleshooting Guide ​

Common issues and solutions for Claude AI development.

API Issues ​

Authentication Errors ​

"Invalid API key" ​

bash
# Check if key is set
echo $ANTHROPIC_API_KEY

# Reset environment variable
export ANTHROPIC_API_KEY="your-key-here"
source ~/.bashrc

# Verify in Python
python -c "import os; print(os.getenv('ANTHROPIC_API_KEY')[:10])"

"Rate limit exceeded" ​

python
# Implement exponential backoff
import time
from anthropic import RateLimitError

def retry_with_backoff(func, max_retries=5):
    for i in range(max_retries):
        try:
            return func()
        except RateLimitError:
            wait_time = (2 ** i) + random.random()
            print(f"Rate limited, waiting {wait_time:.2f}s")
            time.sleep(wait_time)
    raise Exception("Max retries exceeded")

Connection Issues ​

"Connection timeout" ​

python
# Increase timeout
client = Anthropic(timeout=60.0, max_retries=3)

"SSL certificate verification failed" ​

python
# For corporate networks
import httpx
client = Anthropic(
    http_client=httpx.Client(verify=False)  # Not recommended for production
)

Claude Code Issues ​

Installation Problems ​

"Command not found: claude-code" ​

bash
# Check installation
which claude-code

# Add to PATH
export PATH=$PATH:/usr/local/bin

# Reinstall
curl -L https://releases.anthropic.com/claude-code/latest/linux | sudo tee /usr/local/bin/claude-code
chmod +x /usr/local/bin/claude-code

"Permission denied" ​

bash
# Fix permissions
chmod +x /usr/local/bin/claude-code

# Or install in user directory
mkdir -p ~/.local/bin
curl -L https://releases.anthropic.com/claude-code/latest/linux -o ~/.local/bin/claude-code
chmod +x ~/.local/bin/claude-code
export PATH=$PATH:~/.local/bin

Configuration Issues ​

"API key not configured" ​

bash
# Set API key
claude-code config set api_key sk-ant-api03-...

# Verify configuration
claude-code config list

"Context too large" ​

bash
# Reduce context size
claude-code --max-files 10 "your command"

# Update exclude patterns
# Edit ~/.claude/settings.json
{
  "context": {
    "exclude_patterns": [
      "node_modules/**",
      "*.pyc", 
      ".git/**",
      "dist/**"
    ]
  }
}

Model Issues ​

Model Availability ​

"Model not found" ​

python
# Use available models
models = [
    "claude-3-5-sonnet-20241022",  # Try first
    "claude-3-5-haiku-20241022",   # Fallback
    "claude-3-opus-20240229"       # Alternative
]

for model in models:
    try:
        response = client.messages.create(model=model, ...)
        break
    except Exception as e:
        print(f"Model {model} failed: {e}")
        continue

"Model deprecated" ​

bash
# Check current models
claude-code "what models are currently available?"

# Update to latest
# Check docs.anthropic.com for current model names

Performance Issues ​

"Responses too slow" ​

python
# Use faster model
client.messages.create(
    model="claude-3-5-haiku-20241022",  # Fastest
    max_tokens=1000,
    messages=[...]
)

"High token usage" ​

python
# Optimize prompts
def optimize_prompt(prompt):
    # Remove unnecessary words
    # Use bullet points instead of paragraphs
    # Be more specific to avoid clarification
    return optimized_prompt

Environment Issues ​

Virtual Environment Problems ​

"Module not found" ​

bash
# Check active environment
which python
pip list | grep anthropic

# Activate correct environment
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Reinstall if needed
pip install --force-reinstall anthropic

"Package conflicts" ​

bash
# Create fresh environment
python -m venv fresh_env
source fresh_env/bin/activate
pip install anthropic

Docker Issues ​

"Container can't access API" ​

dockerfile
# Ensure environment variables are passed
ENV ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
bash
# Run container with environment
docker run -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY myapp

Development Issues ​

IDE Integration ​

"Claude Code not working in VS Code" ​

json
// .vscode/settings.json
{
  "terminal.integrated.env.linux": {
    "ANTHROPIC_API_KEY": "your-key-here"
  },
  "terminal.integrated.shellArgs.linux": ["-l"]
}

"Autocomplete not working" ​

bash
# Install shell completion
claude-code --completion bash >> ~/.bashrc
source ~/.bashrc

Git Integration ​

"Auto-commit failing" ​

bash
# Check git configuration
git config --list | grep user

# Set if missing
git config user.name "Your Name"
git config user.email "your@email.com"

"Large files causing issues" ​

bash
# Add to .gitignore
echo "*.log" >> .gitignore
echo "node_modules/" >> .gitignore
echo ".env" >> .gitignore

Network Issues ​

Proxy Configuration ​

"Behind corporate firewall" ​

bash
# Set proxy for Claude
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

# For Python
pip install --proxy http://proxy.company.com:8080 anthropic

"VPN connection issues" ​

python
# Use custom DNS
import httpx

client = Anthropic(
    http_client=httpx.Client(
        proxies="http://your-vpn-proxy:port"
    )
)

Common Error Codes ​

Error CodeMeaningSolution
400Bad RequestCheck request format
401UnauthorizedVerify API key
403ForbiddenCheck account status
429Rate LimitedImplement backoff
500Server ErrorRetry request
502Bad GatewayCheck service status
503UnavailableWait and retry

Debugging Tools ​

Enable Debug Logging ​

python
import logging
logging.basicConfig(level=logging.DEBUG)

# For requests
import httpx
client = Anthropic(
    http_client=httpx.Client(
        transport=httpx.HTTPTransport(retries=3),
        timeout=30.0
    )
)

Monitor API Usage ​

python
# Track token usage
def track_usage(response):
    usage = response.usage
    print(f"Input tokens: {usage.input_tokens}")
    print(f"Output tokens: {usage.output_tokens}")
    print(f"Total cost: ${usage.input_tokens * 0.000003 + usage.output_tokens * 0.000015}")

Test Connection ​

bash
# Quick API test
curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2024-10-22" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-5-haiku-20241022",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "Hi"}]
  }'

Getting Help ​

Support Channels ​

  1. Documentation: docs.anthropic.com
  2. Status Page: status.anthropic.com
  3. Community: Discord
  4. Support: support@anthropic.com

Reporting Issues ​

Include:

  • Error message (full stack trace)
  • Operating system and version
  • Python/Node.js version
  • anthropic package version
  • Minimal code to reproduce
bash
# Gather system info
echo "OS: $(uname -a)"
echo "Python: $(python --version)"
echo "Anthropic: $(pip show anthropic | grep Version)"
echo "Node: $(node --version)"

Still having issues? Check the Error Codes reference or contact support.

Claude Code Documentation Hub

Based on official Anthropic documentation