Initial commit
This commit is contained in:
Zhongwei Li
456
skills/claude-code/references/troubleshooting.md
Normal file
456
skills/claude-code/references/troubleshooting.md
Normal file
@@ -0,0 +1,456 @@
|
||||
# Troubleshooting
|
||||
|
||||
Common issues, debugging, and solutions for Claude Code.
|
||||
|
||||
## Authentication Issues
|
||||
|
||||
### API Key Not Recognized
|
||||
|
||||
**Symptoms:**
|
||||
- "Invalid API key" errors
|
||||
- Authentication failures
|
||||
- 401 Unauthorized responses
|
||||
|
||||
**Solutions:**
|
||||
|
||||
```bash
|
||||
# Verify API key is set
|
||||
echo $ANTHROPIC_API_KEY
|
||||
|
||||
# Re-login
|
||||
claude logout
|
||||
claude login
|
||||
|
||||
# Check API key format (should start with sk-ant-)
|
||||
echo $ANTHROPIC_API_KEY | grep "^sk-ant-"
|
||||
|
||||
# Test API key directly
|
||||
curl https://api.anthropic.com/v1/messages \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-H "content-type: application/json" \
|
||||
-d '{"model":"claude-sonnet-4-5-20250929","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'
|
||||
```
|
||||
|
||||
### Environment Variable Issues
|
||||
|
||||
```bash
|
||||
# Add to shell profile
|
||||
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
|
||||
# Or use .env file
|
||||
echo 'ANTHROPIC_API_KEY=sk-ant-xxxxx' > .claude/.env
|
||||
|
||||
# Verify it's loaded
|
||||
claude config get apiKey
|
||||
```
|
||||
|
||||
## Installation Problems
|
||||
|
||||
### npm Installation Failures
|
||||
|
||||
```bash
|
||||
# Clear npm cache
|
||||
npm cache clean --force
|
||||
|
||||
# Remove and reinstall
|
||||
npm uninstall -g @anthropic-ai/claude-code
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
|
||||
# Use specific version
|
||||
npm install -g @anthropic-ai/claude-code@1.0.0
|
||||
|
||||
# Check installation
|
||||
which claude
|
||||
claude --version
|
||||
```
|
||||
|
||||
### Permission Errors
|
||||
|
||||
```bash
|
||||
# Fix permissions on Unix/Mac
|
||||
sudo chown -R $USER ~/.claude
|
||||
chmod -R 755 ~/.claude
|
||||
|
||||
# Or install without sudo (using nvm)
|
||||
nvm install 18
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
### Python Installation Issues
|
||||
|
||||
```bash
|
||||
# Upgrade pip
|
||||
pip install --upgrade pip
|
||||
|
||||
# Install in virtual environment
|
||||
python -m venv claude-env
|
||||
source claude-env/bin/activate
|
||||
pip install claude-code
|
||||
|
||||
# Install with --user flag
|
||||
pip install --user claude-code
|
||||
```
|
||||
|
||||
## Connection & Network Issues
|
||||
|
||||
### Proxy Configuration
|
||||
|
||||
```bash
|
||||
# Set proxy environment variables
|
||||
export HTTP_PROXY=http://proxy.company.com:8080
|
||||
export HTTPS_PROXY=http://proxy.company.com:8080
|
||||
export NO_PROXY=localhost,127.0.0.1
|
||||
|
||||
# Configure in settings
|
||||
claude config set proxy http://proxy.company.com:8080
|
||||
|
||||
# Test connection
|
||||
curl -x $HTTP_PROXY https://api.anthropic.com
|
||||
```
|
||||
|
||||
### SSL/TLS Errors
|
||||
|
||||
```bash
|
||||
# Trust custom CA certificate
|
||||
export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt
|
||||
|
||||
# Disable SSL verification (not recommended for production)
|
||||
export NODE_TLS_REJECT_UNAUTHORIZED=0
|
||||
|
||||
# Update ca-certificates
|
||||
sudo update-ca-certificates # Debian/Ubuntu
|
||||
sudo update-ca-trust # RHEL/CentOS
|
||||
```
|
||||
|
||||
### Firewall Issues
|
||||
|
||||
```bash
|
||||
# Check connectivity to Anthropic API
|
||||
ping api.anthropic.com
|
||||
telnet api.anthropic.com 443
|
||||
|
||||
# Test HTTPS connection
|
||||
curl -v https://api.anthropic.com
|
||||
|
||||
# Check firewall rules
|
||||
sudo iptables -L # Linux
|
||||
netsh advfirewall show allprofiles # Windows
|
||||
```
|
||||
|
||||
## MCP Server Problems
|
||||
|
||||
### Server Not Starting
|
||||
|
||||
```bash
|
||||
# Test MCP server command manually
|
||||
npx -y @modelcontextprotocol/server-filesystem /tmp
|
||||
|
||||
# Check server logs
|
||||
cat ~/.claude/logs/mcp-*.log
|
||||
|
||||
# Verify environment variables
|
||||
echo $GITHUB_TOKEN # For GitHub MCP
|
||||
|
||||
# Test with MCP Inspector
|
||||
npx @modelcontextprotocol/inspector
|
||||
```
|
||||
|
||||
### Connection Timeouts
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-server": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-example"],
|
||||
"timeout": 30000,
|
||||
"retries": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Permission Denied
|
||||
|
||||
```bash
|
||||
# Check file permissions
|
||||
ls -la /path/to/mcp/server
|
||||
|
||||
# Make executable
|
||||
chmod +x /path/to/mcp/server
|
||||
|
||||
# Check directory access
|
||||
ls -ld /path/to/allowed/directory
|
||||
```
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow Responses
|
||||
|
||||
**Check network latency:**
|
||||
```bash
|
||||
ping api.anthropic.com
|
||||
```
|
||||
|
||||
**Use faster model:**
|
||||
```bash
|
||||
claude --model haiku "simple task"
|
||||
```
|
||||
|
||||
**Reduce context:**
|
||||
```json
|
||||
{
|
||||
"maxTokens": 4096,
|
||||
"context": {
|
||||
"autoTruncate": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Enable caching:**
|
||||
```json
|
||||
{
|
||||
"caching": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### High Memory Usage
|
||||
|
||||
```bash
|
||||
# Clear cache
|
||||
rm -rf ~/.claude/cache/*
|
||||
|
||||
# Limit context window
|
||||
claude config set maxTokens 8192
|
||||
|
||||
# Disable memory
|
||||
claude config set memory.enabled false
|
||||
|
||||
# Close unused sessions
|
||||
claude session list
|
||||
claude session close session-123
|
||||
```
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
```bash
|
||||
# Check rate limits
|
||||
claude usage show
|
||||
|
||||
# Wait and retry
|
||||
sleep 60
|
||||
claude "retry task"
|
||||
|
||||
# Implement exponential backoff in scripts
|
||||
```
|
||||
|
||||
## Tool Execution Errors
|
||||
|
||||
### Bash Command Failures
|
||||
|
||||
**Check sandboxing settings:**
|
||||
```json
|
||||
{
|
||||
"sandboxing": {
|
||||
"enabled": true,
|
||||
"allowedPaths": ["/workspace", "/tmp"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Verify command permissions:**
|
||||
```bash
|
||||
# Make script executable
|
||||
chmod +x script.sh
|
||||
|
||||
# Check PATH
|
||||
echo $PATH
|
||||
which command-name
|
||||
```
|
||||
|
||||
### File Access Denied
|
||||
|
||||
```bash
|
||||
# Check file permissions
|
||||
ls -la file.txt
|
||||
|
||||
# Change ownership
|
||||
sudo chown $USER file.txt
|
||||
|
||||
# Grant read/write permissions
|
||||
chmod 644 file.txt
|
||||
```
|
||||
|
||||
### Write Tool Failures
|
||||
|
||||
```bash
|
||||
# Check disk space
|
||||
df -h
|
||||
|
||||
# Verify directory exists
|
||||
mkdir -p /path/to/directory
|
||||
|
||||
# Check write permissions
|
||||
touch /path/to/directory/test.txt
|
||||
rm /path/to/directory/test.txt
|
||||
```
|
||||
|
||||
## Hook Errors
|
||||
|
||||
### Hooks Not Running
|
||||
|
||||
```bash
|
||||
# Verify hooks.json syntax
|
||||
cat .claude/hooks.json | jq .
|
||||
|
||||
# Check hook script permissions
|
||||
chmod +x .claude/scripts/hook.sh
|
||||
|
||||
# Test hook script manually
|
||||
.claude/scripts/hook.sh
|
||||
|
||||
# Check logs
|
||||
cat ~/.claude/logs/hooks.log
|
||||
```
|
||||
|
||||
### Hook Script Errors
|
||||
|
||||
```bash
|
||||
# Add error handling to hooks
|
||||
#!/bin/bash
|
||||
set -e # Exit on error
|
||||
set -u # Exit on undefined variable
|
||||
|
||||
# Debug hook execution
|
||||
#!/bin/bash
|
||||
set -x # Print commands
|
||||
echo "Hook running: $TOOL_NAME"
|
||||
```
|
||||
|
||||
## Debug Mode
|
||||
|
||||
### Enable Debugging
|
||||
|
||||
```bash
|
||||
# Set debug environment variable
|
||||
export CLAUDE_DEBUG=1
|
||||
export CLAUDE_LOG_LEVEL=debug
|
||||
|
||||
# Run with debug flag
|
||||
claude --debug "task"
|
||||
|
||||
# View debug logs
|
||||
tail -f ~/.claude/logs/debug.log
|
||||
```
|
||||
|
||||
### Verbose Output
|
||||
|
||||
```bash
|
||||
# Enable verbose mode
|
||||
claude --verbose "task"
|
||||
|
||||
# Show all tool calls
|
||||
claude --show-tools "task"
|
||||
|
||||
# Display thinking process
|
||||
claude --show-thinking "task"
|
||||
```
|
||||
|
||||
## Common Error Messages
|
||||
|
||||
### "Model not found"
|
||||
|
||||
```bash
|
||||
# Use correct model name
|
||||
claude --model claude-sonnet-4-5-20250929
|
||||
|
||||
# Update claude-code
|
||||
npm update -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
### "Rate limit exceeded"
|
||||
|
||||
```bash
|
||||
# Wait and retry
|
||||
sleep 60
|
||||
|
||||
# Check usage
|
||||
claude usage show
|
||||
|
||||
# Implement rate limiting in code
|
||||
```
|
||||
|
||||
### "Context length exceeded"
|
||||
|
||||
```bash
|
||||
# Reduce context
|
||||
claude config set maxTokens 100000
|
||||
|
||||
# Summarize long content
|
||||
claude "summarize this codebase"
|
||||
|
||||
# Process in chunks
|
||||
claude "analyze first half of files"
|
||||
```
|
||||
|
||||
### "Timeout waiting for response"
|
||||
|
||||
```bash
|
||||
# Increase timeout
|
||||
claude config set timeout 300
|
||||
|
||||
# Check network connection
|
||||
ping api.anthropic.com
|
||||
|
||||
# Retry with smaller request
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Collect Diagnostic Info
|
||||
|
||||
```bash
|
||||
# System info
|
||||
claude --version
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
# Configuration
|
||||
claude config list --all
|
||||
|
||||
# Recent logs
|
||||
tail -n 100 ~/.claude/logs/session.log
|
||||
|
||||
# Environment
|
||||
env | grep CLAUDE
|
||||
env | grep ANTHROPIC
|
||||
```
|
||||
|
||||
### Report Issues
|
||||
|
||||
1. **Check existing issues**: https://github.com/anthropics/claude-code/issues
|
||||
2. **Gather diagnostic info**
|
||||
3. **Create minimal reproduction**
|
||||
4. **Submit issue** with:
|
||||
- Claude Code version
|
||||
- Operating system
|
||||
- Error messages
|
||||
- Steps to reproduce
|
||||
|
||||
### Support Channels
|
||||
|
||||
- **Documentation**: https://docs.claude.com/claude-code
|
||||
- **GitHub Issues**: https://github.com/anthropics/claude-code/issues
|
||||
- **Support Portal**: support.claude.com
|
||||
- **Community Discord**: discord.gg/anthropic
|
||||
|
||||
## See Also
|
||||
|
||||
- Installation guide: `references/getting-started.md`
|
||||
- Configuration: `references/configuration.md`
|
||||
- MCP setup: `references/mcp-integration.md`
|
||||
- Best practices: `references/best-practices.md`
|
||||
Reference in New Issue
Block a user