ccs/docs/errors/README.md

CCS Error Codes

Quick reference for CCS error codes and solutions.

Error Categories

• E100-E199: Configuration Errors
• E200-E299: Profile Management Errors
• E300-E399: Claude CLI Detection Errors
• E400-E499: Network/API Errors
• E500-E599: File System Errors
• E900-E999: Internal Errors

---

Configuration Errors

E101: Configuration File Missing

Cause: ~/.ccs/config.json not found

Solutions:

# Reinstall CCS
npm install -g @kaitranntt/ccs --force

---

E102: Invalid JSON in Configuration

Cause: Corrupted or malformed config.json

Solutions:

# Backup and reset
mv ~/.ccs/config.json ~/.ccs/config.json.backup
npm install -g @kaitranntt/ccs --force

---

E103: Invalid Profile Configuration

Cause: Profile settings reference non-existent settings file

Solutions:

# Check profile settings
cat ~/.ccs/config.json

# Fix path or recreate profile
ccs auth create <profile>

---

Profile Management Errors

E104: Profile Not Found

Cause: Requested profile doesn't exist

Solutions:

# List available profiles
ccs auth list

# Create new profile
ccs auth create <name>

# Use existing profile
ccs <profile> "your prompt"

---

E105: Profile Already Exists

Cause: Attempting to create profile that already exists

Solutions:

# Use different name
ccs auth create <different-name>

# Or overwrite existing (use with caution)
ccs auth create <name> --force

---

E106: Cannot Delete Default Profile

Cause: Attempting to remove currently active default profile

Solutions:

# Set different default first
ccs auth default <other-profile>

# Then remove old default
ccs auth remove <old-profile>

---

E107: Invalid Profile Name

Cause: Profile name contains invalid characters

Solutions:

# Use only: alphanumeric, dash, underscore
# Valid:   work, test-env, my_profile
# Invalid: my profile, test@work, profile!

---

Claude CLI Errors

E301: Claude CLI Not Found

Cause: Claude CLI not installed or not in PATH

Solutions:

# Install Claude CLI
# See: https://docs.claude.com/en/docs/claude-code/installation

# Verify installation
command -v claude    # Unix
Get-Command claude   # Windows

# Custom path (if installed elsewhere)
export CCS_CLAUDE_PATH="/path/to/claude"

---

E302: Claude CLI Version Incompatible

Cause: Claude CLI version doesn't meet minimum requirements

Solutions:

# Update Claude CLI
# Follow official update guide

# Check version
claude --version

---

E303: Claude CLI Execution Failed

Cause: Claude CLI failed to start or crashed

Solutions:

# Test Claude directly
claude --version

# Check permissions
ls -la $(which claude)

# Reinstall if needed

---

Network/API Errors

E401: GLMT Proxy Timeout

Cause: GLMT proxy server failed to start within 30 seconds

Solutions:

# Check port conflicts
lsof -i :19889  # or random port shown in error

# Use non-proxy GLM instead
ccs glm "your prompt"

# Enable debug mode
export CCS_DEBUG=1
ccs glmt "test"

---

E402: API Key Missing

Cause: Required API key not configured

Solutions:

# For GLM/GLMT/Kimi
# Add to settings file or use Claude login
claude /login

---

E403: API Authentication Failed

Cause: Invalid or expired API credentials

Solutions:

# Re-authenticate
claude /login

# Check API key validity
# Verify in Claude dashboard

---

E404: API Rate Limit Exceeded

Cause: Too many requests to API

Solutions:

# Wait and retry
sleep 60

# Check rate limits in API dashboard
# Consider upgrading plan

---

File System Errors

E501: Cannot Create Directory

Cause: Permission denied or path issues

Solutions:

# Fix ownership
sudo chown -R $USER ~/.ccs

# Fix permissions
chmod 755 ~/.ccs

# Retry
npm install -g @kaitranntt/ccs --force

---

E502: Cannot Write File

Cause: Permission denied writing to CCS directories

Solutions:

# Fix permissions
sudo chown -R $USER ~/.ccs ~/.claude
chmod -R 755 ~/.ccs ~/.claude

# Check disk space
df -h ~

---

E503: Cannot Read File

Cause: File doesn't exist or permission denied

Solutions:

# Check file exists
ls -la <file-path-from-error>

# Fix permissions
chmod 644 <file-path>

# Recreate if missing
ccs auth create <profile>

---

E504: Instance Directory Not Found

Cause: Profile instance directory missing

Solutions:

# Recreate profile
ccs auth remove <profile>
ccs auth create <profile>

---

Internal Errors

E900: Internal Error

Cause: Unexpected error in CCS code

Solutions:

# Report bug with debug output
export CCS_DEBUG=1
ccs <your-command> 2>&1 | tee error.log

# Report at: https://github.com/kaitranntt/ccs/issues

---

E901: Invalid State

Cause: CCS detected inconsistent internal state

Solutions:

# Run health check
ccs doctor

# Reset CCS data (backup first!)
mv ~/.ccs ~/.ccs.backup
npm install -g @kaitranntt/ccs --force

---

Getting Help

If you encounter an error not listed here:

1. Enable debug mode: export CCS_DEBUG=1
2. Run the failing command
3. Check logs: ~/.ccs/logs/
4. Report issue: https://github.com/kaitranntt/ccs/issues

Include:

• Error code
• Full error message
• Debug output
• OS/platform info
• CCS version: ccs --version