Skip to main content

​
Error Codes Reference

CCS uses standardized exit codes for consistent error handling. This reference covers all exit codes, their meanings, recovery strategies, and debugging techniques.

​
Exit Code Summary

CodeNameRecoverableSeverityCommon Causes
0SUCCESSN/ASuccessNormal execution
1GENERAL_ERRORNoErrorUnspecified errors
2CONFIG_ERRORNoErrorConfig file issues
3NETWORK_ERRORYesWarningConnection failures
4AUTH_ERRORNoErrorAuthentication failures
5BINARY_ERRORNoErrorCLIProxy binary issues
6PROVIDER_ERRORYesWarningProvider API errors
7PROFILE_ERRORNoErrorProfile not found
8PROXY_ERRORNoErrorProxy startup failures
9MIGRATION_ERRORNoErrorConfig migration failures
130USER_ABORTNoInfoUser interrupted (Ctrl+C)
Recoverable: Error might succeed on retry with same parameters Severity: Success (0), Info (130), Warning (3, 6), Error (1, 2, 4, 5, 7, 8, 9)

​
Detailed Error Codes

​
Exit Code 0: SUCCESS

Name: SUCCESS Recoverable: N/A Severity: Success Description: Command completed successfully without errors. Examples: 
ccs gemini --help           # Exit 0
ccs --version               # Exit 0
ccs doctor                  # Exit 0 (all checks pass)
Debug Mode: No output in debug mode (success is silent).

​
Exit Code 1: GENERAL_ERROR

Name: GENERAL_ERROR Recoverable: No Severity: Error Description: Unspecified error that doesn’t fit other categories. Often indicates bugs or unexpected conditions. Common Causes:
  • Unhandled exceptions
  • Logic errors in code
  • Unexpected state
Recovery Strategy:
  1. Enable debug mode: CCS_DEBUG=1 ccs <command>
  2. Check stack trace for root cause
  3. Report bug if issue persists
Examples: 
# Invalid argument combination
ccs gemini --unknown-flag   # Exit 1

# Corrupted internal state
ccs api create --name ""    # Exit 1
Debug Output: 
[X] Unexpected error
Exit Code: GENERAL_ERROR (1)
Type: CCSError
Recoverable: false
Stack:
  at handleError (src/errors/error-handler.ts:45)
  at main (src/ccs.ts:123)

​
Exit Code 2: CONFIG_ERROR

Name: CONFIG_ERROR Recoverable: No Severity: Error Description: Configuration file is invalid, corrupted, or has schema errors. Common Causes:
  • Invalid YAML syntax
  • Schema version mismatch
  • Missing required fields
  • Invalid field values
  • Corrupted config file
Recovery Strategy:
  1. Validate syntax: ccs doctor
  2. Auto-repair: ccs doctor --fix
  3. Manual edit: Fix syntax in ~/.ccs/config.yaml
  4. Reset config: Delete ~/.ccs/config.yaml and run ccs setup
Examples: 
# Invalid YAML syntax
# config.yaml has malformed YAML
ccs gemini   # Exit 2: "Config file has invalid YAML syntax"

# Schema version mismatch
# config.yaml has version: 99
ccs gemini   # Exit 2: "Unsupported config version: 99"
Debug Output: 
[X] Config file validation failed
Path: /home/user/.ccs/config.yaml
Exit Code: CONFIG_ERROR (2)
Details: Invalid value for 'cliproxy.variants.myvariant.port': must be 8318-8417
Related:

​
Exit Code 3: NETWORK_ERROR

Name: NETWORK_ERROR Recoverable: Yes Severity: Warning Description: Network connection failed. Retry may succeed if network is restored. Common Causes:
  • No internet connection
  • Remote proxy unreachable
  • DNS resolution failure
  • Firewall blocking connection
  • Timeout exceeded
Recovery Strategy:
  1. Check network: Verify internet connection
  2. Test connectivity: ping <proxy-host>
  3. Increase timeout: --proxy-timeout 10000
  4. Use local fallback: Remove --remote-only flag
  5. Retry: Re-run command after network restored
Examples: 
# Remote proxy unreachable
ccs gemini --proxy-host proxy.example.com --remote-only
# Exit 3: "Failed to connect to remote proxy: ECONNREFUSED"

# DNS resolution failure
ccs gemini --proxy-host invalid-host.example.com
# Exit 3: "DNS lookup failed: ENOTFOUND"
Debug Output: 
[X] Network connection failed
URL: https://proxy.example.com:8443/health
Exit Code: NETWORK_ERROR (3)
Status Code: N/A (connection refused)
Recoverable: true (retry may succeed)
Related:

​
Exit Code 4: AUTH_ERROR

Name: AUTH_ERROR Recoverable: No Severity: Error Description: Authentication or authorization failed. Requires user intervention to fix credentials. Common Causes:
  • OAuth token expired/revoked
  • Invalid API key
  • Missing authentication
  • Wrong credentials
  • Account suspended
Recovery Strategy:
  1. Re-authenticate: ccs <profile> --auth
  2. Check credentials: Verify API keys in config
  3. Logout and login: ccs <profile> --logout then --auth
  4. Add new account: ccs <profile> --auth --add
  5. Check provider status: Verify account is active
Examples: 
# OAuth token expired
ccs gemini   # Exit 4: "OAuth token expired. Run with --auth to refresh"

# Invalid API key
ccs glm      # Exit 4: "Authentication failed: invalid API key"

# Account not found
ccs gemini --use unknown@example.com
# Exit 4: "Account not found: unknown@example.com"
Debug Output: 
[X] Authentication failed
Provider: gemini
Exit Code: AUTH_ERROR (4)
Details: OAuth token expired (issued 7 days ago, valid for 7 days)
Hint: Run 'ccs gemini --auth' to refresh token
Related:

​
Exit Code 5: BINARY_ERROR

Name: BINARY_ERROR Recoverable: No Severity: Error Description: CLIProxyAPI binary is missing, corrupted, or incompatible. Common Causes:
  • Binary not installed
  • Binary corrupted
  • Version mismatch
  • Permission denied
  • Unsupported platform
Recovery Strategy:
  1. Reinstall binary: ccs cliproxy install --force
  2. Check version: ccs cliproxy version
  3. Verify permissions: chmod +x ~/.ccs/cliproxy/bin/CLIProxyAPI
  4. Platform check: Ensure platform is supported
  5. Clean install: Delete ~/.ccs/cliproxy/bin/ and reinstall
Examples: 
# Binary not found
ccs gemini   # Exit 5: "CLIProxyAPI binary not found. Run 'ccs cliproxy install'"

# Version mismatch
ccs gemini   # Exit 5: "Binary version mismatch: expected v7.2, found v6.0"

# Permission denied
ccs gemini   # Exit 5: "Cannot execute binary: EACCES"
Debug Output: 
[X] CLIProxyAPI binary error
Path: /home/user/.ccs/cliproxy/bin/CLIProxyAPI
Exit Code: BINARY_ERROR (5)
Issue: Binary version mismatch
Expected: v7.2.0
Found: v6.0.1
Action: Run 'ccs cliproxy install --force' to update
Related:

​
Exit Code 6: PROVIDER_ERROR

Name: PROVIDER_ERROR Recoverable: Yes Severity: Warning Description: Provider API returned an error. May be temporary (rate limiting, maintenance). Common Causes:
  • Rate limiting
  • Provider API down
  • Quota exceeded
  • Invalid request
  • Provider-side issues
Recovery Strategy:
  1. Retry: Wait and re-run command
  2. Check status: Visit provider status page
  3. Switch provider: Use alternative provider
  4. Check quota: Verify API usage limits
  5. Report issue: Contact provider support if persistent
Examples: 
# Rate limiting
ccs gemini   # Exit 6: "Provider rate limit exceeded. Retry after 60 seconds"

# Provider API down
ccs codex    # Exit 6: "Provider API unavailable: 503 Service Unavailable"

# Quota exceeded
ccs agy      # Exit 6: "API quota exceeded. Upgrade plan or wait for reset"
Debug Output: 
[X] Provider API error
Provider: gemini
Exit Code: PROVIDER_ERROR (6)
Status Code: 429 Too Many Requests
Details: Rate limit exceeded (60 req/min quota)
Retry-After: 45 seconds
Recoverable: true (retry after delay)
Related:

​
Exit Code 7: PROFILE_ERROR

Name: PROFILE_ERROR Recoverable: No Severity: Error Description: Profile name not found or invalid. Common Causes:
  • Profile doesn’t exist
  • Typo in profile name
  • Profile not created yet
  • Reserved profile name
Recovery Strategy:
  1. List profiles: ccs auth list or ccs api list
  2. Check spelling: Verify profile name
  3. Create profile: ccs auth create or ccs api create
  4. Check config: Edit ~/.ccs/config.yaml if needed
Examples: 
# Profile not found
ccs unknown-profile   # Exit 7: "Profile not found: unknown-profile"

# Typo
ccs gemnii   # Exit 7: "Profile not found: gemnii. Did you mean: gemini?"

# Reserved name
ccs auth create --name config
# Exit 7: "Profile name 'config' is reserved"
Debug Output: 
[X] Profile not found
Profile: myprofile
Exit Code: PROFILE_ERROR (7)
Available profiles:
  - gemini (OAuth)
  - codex (OAuth)
  - glm (API)
  - work (account)
Hint: Run 'ccs auth list' to see all profiles
Related:

​
Exit Code 8: PROXY_ERROR

Name: PROXY_ERROR Recoverable: No Severity: Error Description: CLIProxyAPI failed to start or crashed. Common Causes:
  • Port already in use
  • Binary crashed
  • Insufficient permissions
  • Resource limits exceeded
  • Configuration error
Recovery Strategy:
  1. Check port: lsof -i :<port> or netstat -an | grep <port>
  2. Kill existing: pkill CLIProxyAPI
  3. Retry: Re-run command
  4. Check logs: ~/.ccs/cliproxy/logs/error.log
  5. Reinstall binary: ccs cliproxy install --force
Examples: 
# Port in use
ccs gemini   # Exit 8: "Failed to start proxy: port 8317 already in use"

# Binary crashed
ccs gemini   # Exit 8: "Proxy process exited unexpectedly: exit code 1"

# Permission denied
ccs gemini   # Exit 8: "Cannot bind to port 8317: EACCES"
Debug Output: 
[X] Proxy startup failed
Port: 8317
Exit Code: PROXY_ERROR (8)
Reason: Port already in use
Process: CLIProxyAPI (PID 12345)
Action: Run 'pkill CLIProxyAPI' and retry
Related:

​
Exit Code 9: MIGRATION_ERROR

Name: MIGRATION_ERROR Recoverable: No Severity: Error Description: Config migration from legacy format failed. Common Causes:
  • Corrupted legacy config
  • Disk full
  • Permission denied
  • Conflicting profiles
  • Invalid legacy data
Recovery Strategy:
  1. Rollback: ccs migrate --rollback
  2. Dry run: ccs migrate --dry-run to preview
  3. Manual migration: Edit config files manually
  4. Fresh start: Delete ~/.ccs/ and run ccs setup
  5. Restore backup: Copy from ~/.ccs/backup-v1-*/
Examples: 
# Corrupted legacy config
ccs migrate   # Exit 9: "Migration failed: invalid JSON in config.json"

# Conflicting profiles
ccs migrate   # Exit 9: "Profile name conflict: 'work' exists in both sources"

# Disk full
ccs migrate   # Exit 9: "Migration failed: ENOSPC (no space left on device)"
Debug Output: 
[X] Migration failed
From: v1 (JSON)
To: v6 (YAML)
Exit Code: MIGRATION_ERROR (9)
Backup: /home/user/.ccs/backup-v1-2026-01-05/
Error: Profile name conflict: 'work'
Action: Resolve conflicts manually or rollback
Related:

​
Exit Code 130: USER_ABORT

Name: USER_ABORT Recoverable: No Severity: Info Description: User interrupted execution with Ctrl+C (SIGINT). Common Causes:
  • User pressed Ctrl+C
  • Process killed by signal
  • Terminal closed
Recovery Strategy:
  • None needed (intentional user action)
Examples: 
# User interrupts OAuth flow
ccs gemini --auth
# (Press Ctrl+C during browser auth)
# Exit 130: "Interrupted by user"

# User cancels long operation
ccs doctor --fix
# (Press Ctrl+C during checks)
# Exit 130
Debug Output: 
[X] Interrupted by user
Exit Code: USER_ABORT (130)
Cleanup: All spawned processes terminated

​
Error Handling Utilities

​
Check Exit Code

# Bash
ccs gemini
if [ $? -eq 0 ]; then
  echo "Success"
elif [ $? -eq 3 ]; then
  echo "Network error, retry?"
else
  echo "Failed with exit code $?"
fi

# PowerShell
ccs gemini
if ($LASTEXITCODE -eq 0) {
  Write-Host "Success"
} elseif ($LASTEXITCODE -eq 3) {
  Write-Host "Network error, retry?"
} else {
  Write-Host "Failed with exit code $LASTEXITCODE"
}

​
Debug Mode

Enable verbose error output: 
CCS_DEBUG=1 ccs gemini

# Output includes:
# - Exit code name and number
# - Error type
# - Stack trace (first 5 lines)
# - Recoverable flag
# - Additional context

​
Recoverable Errors

Exit codes 3 and 6 are recoverable. Retry logic: 
#!/bin/bash
MAX_RETRIES=3
RETRY_DELAY=5

for i in $(seq 1 $MAX_RETRIES); do
  ccs gemini
  EXIT_CODE=$?

  # Success
  if [ $EXIT_CODE -eq 0 ]; then
    exit 0
  fi

  # Recoverable (3=NETWORK_ERROR, 6=PROVIDER_ERROR)
  if [ $EXIT_CODE -eq 3 ] || [ $EXIT_CODE -eq 6 ]; then
    echo "Retry $i/$MAX_RETRIES in ${RETRY_DELAY}s..."
    sleep $RETRY_DELAY
    continue
  fi

  # Non-recoverable
  echo "Failed with non-recoverable error: $EXIT_CODE"
  exit $EXIT_CODE
done

echo "Max retries exceeded"
exit $EXIT_CODE

​
Common Error Patterns

​
Pattern: OAuth Flow Failures

Exit Code: 4 (AUTH_ERROR) Symptoms:
  • Browser doesn’t open
  • Token refresh fails
  • “Authentication required” message
Solutions: 
# Re-authenticate
ccs <profile> --auth

# Add new account
ccs <profile> --auth --add

# Logout and login
ccs <profile> --logout
ccs <profile> --auth

​
Pattern: Remote Proxy Issues

Exit Codes: 3 (NETWORK_ERROR), 8 (PROXY_ERROR) Symptoms:
  • “Connection refused”
  • “Timeout exceeded”
  • “Proxy unreachable”
Solutions: 
# Increase timeout
ccs <profile> --proxy-timeout 10000

# Use local fallback
ccs <profile> --local-proxy

# Test connectivity
ping <proxy-host>
curl http://<proxy-host>:<port>/health

​
Pattern: Config Corruption

Exit Code: 2 (CONFIG_ERROR) Symptoms:
  • “Invalid YAML syntax”
  • “Schema validation failed”
  • “Unsupported version”
Solutions: 
# Auto-repair
ccs doctor --fix

# Validate only
ccs doctor

# Reset config
rm ~/.ccs/config.yaml
ccs setup

​
Troubleshooting Workflow

  1. Read error message - Often contains fix instructions
  2. Enable debug mode - CCS_DEBUG=1 for details
  3. Check exit code - Determines if recoverable
  4. Run doctor - ccs doctor for health check
  5. Check logs - ~/.ccs/cliproxy/logs/error.log
  6. Consult docs - Provider-specific guides
  7. Report bug - If issue persists, open GitHub issue