Troubleshooting Guide

claude --version

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

claude /doctor

node --version
# Should output v18.x.x or higher

# Use nvm to manage Node.js versions (recommended)
nvm install 22
nvm use 22

# Or download and install directly
# Visit https://nodejs.org/ to download the LTS version

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

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

# Create a user-level global package directory
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH (write to ~/.bashrc or ~/.zshrc)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

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

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc

# Install and use Node.js
nvm install 22
nvm use 22

# Node.js installed via nvm doesn't require sudo
npm install -g @anthropic-ai/claude-code

npm ERR! network request to https://registry.npmjs.org/ failed
npm ERR! code ETIMEDOUT

# Temporarily use the Taobao mirror
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# Or permanently set the mirror
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

# Set npm proxy
npm config set proxy http://your-proxy-address:port
npm config set https-proxy http://your-proxy-address:port

# After installation, you can remove the proxy settings
npm config delete proxy
npm config delete https-proxy

claude : File C:\Users\xxx\AppData\Roaming\npm\claude.ps1 cannot be loaded
because running scripts is disabled on this system.

# Open PowerShell as administrator and run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then run claude again
claude

# Run directly in CMD
claude

cr_xxxxxxxxxxxxxxxx

# View current environment variable
echo $ANTHROPIC_API_KEY

# Correct setup (QCode.cc key)
export ANTHROPIC_API_KEY="cr_your-key"

# QCode.cc's Base URL
export ANTHROPIC_BASE_URL="https://your-service-address"

# 1. Check current configuration
echo $ANTHROPIC_BASE_URL

# 2. Confirm URL format is correct
#    - Must start with https://
#    - No trailing slash /
#    - Should not contain paths (like /v1/messages)

# Correct example
export ANTHROPIC_BASE_URL="https://api.example.com"

# Incorrect examples
export ANTHROPIC_BASE_URL="http://api.example.com"      # Missing https
export ANTHROPIC_BASE_URL="https://api.example.com/"    # Extra trailing slash
export ANTHROPIC_BASE_URL="https://api.example.com/v1"  # Extra path

Error: connect ETIMEDOUT
Error: getaddrinfo ENOTFOUND api.example.com

# 1. Check if proxy is correctly set
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY

# 2. Test network connectivity
curl -v https://your-service-address/health

# 3. If using a proxy, ensure Claude Code can use it
export HTTP_PROXY="http://proxy-address:port"
export HTTPS_PROXY="http://proxy-address:port"

# 4. If you don't need a proxy but have one set, unset it
unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY

Error: unable to verify the first certificate
Error: self signed certificate in certificate chain

# Solution 1: Update system CA certificates
# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates

# macOS
brew install ca-certificates

# Solution 2: For corporate network mitm certificates, set Node.js to trust them
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.crt"

# Solution 3: Temporarily skip certificate verification (only for testing, not recommended for long-term use)
export NODE_TLS_REJECT_UNAUTHORIZED=0

# Test basic connectivity
curl -s -o /dev/null -w "%{http_code}" \
  https://your-service-address/health

# Test API call (replace with your key and address)
curl https://your-service-address/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_your-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Error: EACCES: permission denied, open '/path/to/file'

# 1. Check file permissions
ls -la /path/to/file

# 2. Ensure current user has read/write permissions
chmod u+rw /path/to/file

# 3. Check directory permissions (Claude needs write permission to create new files)
chmod u+w /path/to/directory

# 4. If file was created by root, change ownership
sudo chown $(whoami) /path/to/file

# View current permission settings
claude /permissions

# Configure allowed directories in settings.json
# ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Read files in /home/user/projects/**",
      "Write files in /home/user/projects/**",
      "Execute bash commands"
    ]
  }
}

fatal: unable to access 'https://github.com/xxx/xxx.git/':
The requested URL returned error: 403

# 1. Check Git configuration
git config --list

# 2. Confirm SSH key or Token configuration
ssh -T git@github.com          # Test SSH connection
gh auth status                  # Test GitHub CLI authentication

# 3. If using HTTPS, check credentials
git config credential.helper    # View credential helper

# 4. Ensure Claude Code is in the correct Git repository
git status                      # Confirm you're in the repository directory

# View permission configuration
claude /permissions

# If it's a project you trust, you can configure allowed commands in CLAUDE.md
# CLAUDE.md
## Allowed Commands
allowedTools:

  - Bash(npm run *)
  - Bash(pnpm *)
  - Bash(git *)
  - Bash(docker compose *)

# Test latency to the server
ping service-address

# If latency exceeds 500ms, consider:
# 1. Check if proxy configuration is optimal
# 2. Try using at different times (avoid peak hours)
# 3. Contact QCode.cc customer service for optimal nodes

# Solution 1: Compress context (retain key information)
/compact

# Solution 2: Clear completely (if you can start over)
/clear

# Solution 3: Streamline each input
# Don't send large amounts of file content at once
# Use @ to reference files instead of pasting
# Handle one task at a time

# 1. Check Node.js memory usage
node -e "console.log(process.memoryUsage())"

# 2. Upgrade Node.js to the latest LTS version
nvm install 22
nvm use 22

# 3. If the problem persists, limit Node.js maximum memory
export NODE_OPTIONS="--max-old-space-size=4096"

# 4. Restart Claude Code
# Exit current session and restart
exit
claude

# Occasional 429
# → Wait 30 seconds for automatic retry, Claude Code has built-in retry logic

# Frequent 429
# → Reduce request frequency
# → Use /compact to reduce context size
# → Avoid running multiple Claude Code instances simultaneously

# Persistent 429
# → Check if plan quota has been exhausted
# → Log in to QCode.cc Dashboard to view usage
# → Consider upgrading your plan

Error: 529 API Overloaded
The API is temporarily overloaded. Please try again later.

# 1. Check if properly installed
which claude
npm list -g @anthropic-ai/claude-code

# 2. View detailed error information
claude --debug

# 3. Try clearing cache and restarting
rm -rf ~/.claude/cache
claude

# 1. Confirm file location is correct
ls -la CLAUDE.md                # Project root directory
ls -la .claude/CLAUDE.md        # Project private configuration
ls -la ~/.claude/CLAUDE.md      # Global configuration

# 2. Confirm file encoding is UTF-8
file CLAUDE.md
# Should display: CLAUDE.md: UTF-8 Unicode text

# 3. Confirm no syntax errors (although it's Markdown, some special characters may cause parsing issues)
# Avoid using special markers other than ``` in CLAUDE.md

# 4. Restart Claude Code for configuration to take effect
# Exit and re-enter

# 1. Check terminal encoding settings
echo $LANG
# Should include UTF-8, for example en_US.UTF-8 or zh_CN.UTF-8

# 2. Set correct encoding
export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8

# 3. Confirm terminal supports UTF-8
# macOS Terminal / iTerm2 supports by default
# Windows Terminal supports by default
# Windows CMD requires: chcp 65001

# 1. First resolve Git conflicts
git status     # View conflicting files
git diff       # View conflict content

# 2. Let Claude help resolve conflicts
> "View the current git conflict files and help me resolve these conflicts. Keep changes from both sides."

# 3. Continue after resolution
git add .
git commit -m "resolve merge conflicts"

# Ensure container has Node.js 22+
docker run -it node:22-slim bash

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Pass necessary environment variables
docker run -it \
  -e ANTHROPIC_API_KEY="cr_your-key" \
  -e ANTHROPIC_BASE_URL="https://your-service-address" \
  -v $(pwd):/workspace \
  -w /workspace \
  node:22-slim claude

1. Quick Self-Check
   ├── claude --version (is version latest)
   ├── claude /doctor (automatic diagnostics)
   └── node --version (Node.js ≥ 18)

2. Network Connectivity
   ├── curl test API address
   ├── Check proxy/VPN settings
   └── Check DNS resolution

3. Authentication Configuration
   ├── Is ANTHROPIC_API_KEY format correct
   ├── Is ANTHROPIC_BASE_URL correct
   └── Is key expired

4. Permission Check
   ├── File system permissions
   ├── Git permissions
   └── Claude Code permission configuration

5. Performance Optimization
   ├── /compact to compress context
   ├── /model to switch to appropriate model
   └── .claudeignore to exclude large files

6. If none of the above solves it → Get Help