# Troubleshooting Guide

## Key configured, requests still failing? Check in this order

The rest of this page is organized by error code; if you **already filled in the key and the URLs exactly as documented and requests still fail**, walk this checklist first (curl self-test and HTTP-code reading: [Endpoints and API paths](/docs/getting-started/endpoints-and-api-paths), section 5):

1. **Run one curl self-test first.** Interpret the code: `401` = key problem; `404` = wrong path prefix; `400` with `model_not_available_on_endpoint` = wrong protocol (not the key — see item 4); connection never establishes = network/proxy, see item 6.
2. **Right variable, wrong slot.** `ANTHROPIC_AUTH_TOKEN` is sent as the `Authorization: Bearer` header, `ANTHROPIC_API_KEY` as `x-api-key` — put the key in the wrong one and the gateway never sees valid credentials. **Stale variables in your environment override current settings**: run `env | grep -i anthropic` and `env | grep -i openai` and remove leftovers.
3. **Base URL shape.** Claude Code family: `https://api.qcode.cc/api` (**no `/v1`**); OpenAI SDK / compatible clients: `https://api.qcode.cc/openai/v1`; Codex CLI in its config file: `https://api.qcode.cc/openai` with `wire_api = "responses"`. One segment too many or too few = 404.
4. **Protocol / model mismatch.** Sending a Claude model to the OpenAI endpoint returns `model_not_available_on_endpoint` before authentication — switch endpoint or model using the matrix in [Endpoints and API paths](/docs/getting-started/endpoints-and-api-paths) section 2.
5. **Client-version regressions (Claude Code):**
   - **2.1.265–2.1.267**: every request 400s (the Artifact tool schema is rejected) — upgrade to **≥2.1.268** or set `CLAUDE_CODE_DISABLE_ARTIFACT=1`.
   - **2.1.275**: with `ANTHROPIC_BASE_URL` pointing at a gateway, every request fails with `400 … Input tag 'advisor_20260301'` — upgrade to **≥2.1.276**.
   - `Unexpected value(s) … anthropic-beta` errors — set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.
6. **System proxy vs access domain.** `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` reroute traffic; add `*.qcode.cc` to `NO_PROXY` or unset them temporarily and retry.
7. **Still stuck**: look the request up at [probe.qcode.cc](https://probe.qcode.cc) with your key to see what actually went out, then **contact support with the request id** (live chat or hi@qcode.cc).

Error-code semantics live in [Error codes](/docs/reference/errors); for "can my subscription act as an API" questions see [Subscriptions vs API Keys vs QCode Keys](/docs/reference/subscription-vs-api-key).

Don't panic if you encounter issues while using Claude Code. This guide is organized following the "Quick Self-Check → Step-by-Step Troubleshooting → Solutions" flow to help you efficiently locate and resolve problems.

## Quick Self-Check

When you encounter issues, start with these three quick checks—80% of problems can be identified at this step.

### 1. Check Claude Code Version

```bash
claude --version
```

Make sure you are using the latest version. Claude Code updates frequently, and many issues have been fixed in newer versions.

**Upgrade to the latest version:**

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

### 2. Run Automatic Diagnostics

```bash
claude /doctor
```

The `/doctor` command automatically checks:
- Whether Node.js version meets requirements (≥ 18)
- Whether the API Key is valid
- Whether the network connection is normal
- Whether the configuration file has syntax errors

### 3. Verify Node.js Version

Claude Code requires Node.js 18 or higher:

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

If the version is too low, please upgrade:

```bash
# 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
```

## Installation Issues

### npm install Permission Error

**Symptoms:**

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

**Solution 1: Use sudo (quick but not recommended for long-term use)**

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

**Solution 2: Change npm global directory (recommended)**

```bash
# 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
```

**Solution 3: Use nvm to manage Node.js**

```bash
# 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
```

### Network Issues Causing Installation Failure

**Symptoms:**

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

**Solution: Use a domestic mirror**

```bash
# 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
```

If you use a proxy:

```bash
# 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
```

### Windows PowerShell Execution Policy

**Symptoms:**

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

**Solution:**

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

# Then run claude again
claude
```

Or use CMD instead of PowerShell:

```cmd
# Run directly in CMD
claude
```

## Connection Issues

Connection issues are the most common type of problem encountered by users in China.

### API Key Format Error

**QCode.cc API Key format:**

```text
cr_xxxxxxxxxxxxxxxx
```

Note that the prefix is `cr_`, not Anthropic's official `sk-ant-`.

**Check API Key configuration:**

```bash
# View current environment variable
echo $ANTHROPIC_AUTH_TOKEN

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

**Common errors:**

| Error | Description |
|------|------|
| Spaces before or after the key | `cr_ xxx` → `cr_xxx` |
| Used official key format | `sk-ant-xxx` is the Anthropic official key, not the QCode.cc key |
| Key truncated | Check if you copied the entire key |
| Used an expired key | Confirm key status in QCode.cc Dashboard |

### ANTHROPIC_BASE_URL Configuration Error

When using QCode.cc service, you need to correctly set the Base URL:

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

**Troubleshooting steps:**

```bash
# 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: the Anthropic leg needs the /api prefix, but no request-path segment
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"

# Wrong: missing https / an extra trailing slash / the path segment spelled out
export ANTHROPIC_BASE_URL="http://api.qcode.cc/api"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api/"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api/v1/messages"
```

### Proxy/VPN Causing Connection Failure

**Symptoms:**

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

**Troubleshooting steps:**

```bash
# 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
```

**VPN Notes:**

- Ensure VPN is not intercepting API requests
- Some VPN split-tunneling rules may affect API connections
- If VPN causes issues, try adding the API domain to the direct connection rules

### SSL/TLS Certificate Issues

**Symptoms:**

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

**Solutions:**

```bash
# 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 Connection

Use curl to directly test API connectivity:

```bash
# 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-5",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

**Expected results:**
- Health check returns `200`
- API call returns JSON response

**Common Issues Reference:**

| curl result | Possible cause | Solution |
|-------------|---------------|----------|
| `connection refused` | Wrong service address or service not running | Check ANTHROPIC_BASE_URL |
| `connection timeout` | Network unreachable or blocked by firewall | Check network/proxy settings |
| `401 Unauthorized` | Invalid API Key | Check if key is correct |
| `403 Forbidden` | Key lacks permissions | Contact service provider |
| SSL related errors | Certificate issue | Refer to SSL section above |

## Permission Issues

### Insufficient File Read/Write Permissions

**Symptoms:**

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

**Solutions:**

```bash
# 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
```

**Claude Code Permission Configuration:**

Claude Code has a permission system to control what operations it can perform. If you find Claude being blocked from performing an operation:

```bash
# 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"
    ]
  }
}
```

### Git Operations Denied

**Symptoms:**

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

**Solutions:**

```bash
# 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
```

### Bash Command Execution Failure

Claude Code may need your confirmation when executing bash commands. If a command keeps getting rejected:

```bash
# 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 *)
```

## Performance Issues

### Slow Response Speed

**Possible causes and solutions:**

| Cause | Diagnosis method | Solution |
|------|------------------|----------|
| Network latency | `ping service-address` | Check network/proxy |
| Using Opus model | `/model` to view | Switch to Sonnet |
| Context too large | `/cost` to view token count | `/compact` to compress |
| High server load | Check HTTP response time | Retry later |

**Network optimization suggestions (for users in China):**

```bash
# 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
```

### Context Overflow

**Symptoms:**
- Claude's responses start "forgetting" what was said before
- Response quality significantly degrades
- Repetitive or contradictory content appears

**Solutions:**

```bash
# 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
```

**Prevention measures:**

- Consider using `/compact` after completing each independent task
- When switching to different topics, don't hesitate to use `/clear`
- Use `.claudeignore` to exclude irrelevant large files
- Use `@` to precisely reference needed files, don't let Claude search globally

### High Memory Usage

**Symptoms:**
- System becomes sluggish
- Claude Code process uses a lot of memory

**Solutions:**

```bash
# 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
```

## Common Error Codes Reference

| Error code | Meaning | Cause | Solution |
|-----------|---------|-------|----------|
| **400** | Bad Request | Incorrect request format | Check for illegal characters in input; update Claude Code to latest version |
| **401** | Unauthorized | API Key invalid or expired | Check `ANTHROPIC_AUTH_TOKEN` setting; confirm key hasn't expired |
| **403** | Forbidden | No permissions | Confirm key has access permissions for the corresponding model |
| **404** | Not Found | Model or path doesn't exist | Check `ANTHROPIC_BASE_URL` and model name are correct |
| **429** | Too Many Requests | Requests too frequent | Wait 30-60 seconds and retry; reduce concurrent requests |
| **500** | Internal Server Error | Server internal error | Retry later; if persistent, contact customer service |
| **502** | Bad Gateway | Upstream service unavailable | Retry later; check for service announcements |
| **503** | Service Unavailable | Service temporarily overloaded | Wait a few minutes and retry |
| **529** | API Overloaded | Claude API overloaded | This is due to high Anthropic server load; wait and retry |

### 429 Detailed: Rate Limiting

429 is the most common error and is worth explaining in detail:

**Triggers:**

1. **Too high request frequency**: Sending too many requests per second
2. **Token consumption too fast**: Consuming a large number of tokens in a short time
3. **Too many concurrent sessions**: Running multiple Claude Code instances simultaneously
4. **Account quota exhausted**: Daily/monthly quota has been used up

**Tiered response:**

```bash
# 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
```

### 529 Detailed: API Overloaded

529 is an Anthropic-specific error code indicating Claude API server overload:

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

**Response measures:**

- This is not your problem; it's a temporary condition on Anthropic's server
- Usually lasts a few minutes to a few tens of minutes
- Wait 1-2 minutes and retry
- If it persists, you can temporarily switch to another model (like GPT series)
- Follow [Anthropic Status](https://status.anthropic.com/) to understand service status

## Other Common Issues

### No Response After Claude Code Starts

```bash
# 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
```

### CLAUDE.md Not Taking Effect

```bash
# 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
```

### Chinese Characters Display as Garbled Text

```bash
# 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
```

### Git Conflicts Causing Claude Operations to Fail

```bash
# 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"
```

### Docker Related Issues (Advanced Users)

If you use Claude Code in a Docker container:

```bash
# 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_AUTH_TOKEN="cr_your-key" \
  -e ANTHROPIC_BASE_URL="https://your-service-address" \
  -v $(pwd):/workspace \
  -w /workspace \
  node:22-slim claude
```

## Troubleshooting Flow Summary

When you encounter issues, troubleshoot following this flow:

```text
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_AUTH_TOKEN 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
```

## Get Help

If none of the above methods resolve your issue, you can get help through these channels:

### QCode.cc Online Customer Service

Click the online customer service icon in the bottom right corner of the [QCode.cc](https://qcode.cc) website. During working hours, you can usually get a response within a few minutes.

**When asking questions, please provide:**
- Claude Code version (output of `claude --version`)
- Operating system and version
- Complete error message
- Solutions you have tried

### GitHub Issues

Claude Code is an open-source project, and you can submit issues on GitHub:

- **Repository address**: [github.com/anthropics/claude-code](https://github.com/anthropics/claude-code)
- Search existing issues to see if anyone has encountered the same problem
- When submitting a new issue, describe it in English (easier to get official response)

### Community Resources

- **Claude Code Official Documentation**: [docs.anthropic.com](https://docs.anthropic.com)
- **Anthropic Service Status**: [status.anthropic.com](https://status.anthropic.com)
- **QCode.cc User Documentation**: [docs.qcode.cc](https://docs.qcode.cc)

> Don't be afraid of problems—most issues have simple solutions. Following this guide's troubleshooting flow, you can usually resolve issues within a few minutes.