Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt

Use this file to discover all available pages before exploring further.

​
Troubleshooting

Common issues and their solutions.
For detailed error code reference and recovery strategies, see Error Codes.

​
Installation Issues

​
Config File Not Found After npm Install

Symptom: 
Config file not found: /home/user/.ccs/config.yaml
Cause: Installed with --ignore-scripts flag. Solution: 
npm install -g @kaitranntt/ccs --force

​
PATH Not Updated

Symptom: ccs command not found after install. Solution:
  1. Restart your terminal
  2. Or manually add to PATH:
    • macOS/Linux: Add ~/.local/bin to PATH
    • Windows: Add %USERPROFILE%\.ccs to PATH

​
Windows-Specific

​
PowerShell Execution Policy

Error: “cannot be loaded because running scripts is disabled” Solution: 
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

​
Claude CLI Not Found

where.exe claude
If missing, install from Claude docs.

​
Claude CLI in Non-Standard Location

​
Set CCS_CLAUDE_PATH

$env:CCS_CLAUDE_PATH = "D:\Program Files\Claude\claude.exe"
[Environment]::SetEnvironmentVariable("CCS_CLAUDE_PATH", $env:CCS_CLAUDE_PATH, "User")

​
Configuration Issues

​
Profile Not Found

Error: Profile 'foo' not found in ~/.ccs/config.yaml Solution: Add profile to config: 
profiles:
  foo: ~/.ccs/foo.settings.json

​
Settings File Missing

Error: Settings file not found: ~/.ccs/foo.settings.json Solution: Create the settings file or fix path in config.

​
Default Profile Missing

Error: Profile 'default' not found Solution: Add default profile: 
default: default
profiles:
  default: ~/.claude/settings.json

​
Quota Issues

​
Quota Shows “N/A (fetch unavailable)”

When quota cannot be fetched, CCS displays “N/A” instead of a percentage. Causes:
  • Network connectivity issues
  • API rate limiting (5-second timeout)
  • Account tier lacks quota API access (403 Forbidden)
  • Token expired (401 Unauthorized)
Solutions:
  1. Check connectivity:
curl https://cloudcode-pa.googleapis.com
  1. Run diagnostics with verbose mode:
ccs cliproxy status --verbose
ccs codex --verbose
  1. Verify account tier: Some free-tier accounts don’t have quota API access. Upgrade to paid tier if needed.
  2. Refresh authentication: 
ccs codex --auth

​
Quota Fetch Error Codes

ErrorHTTP StatusCauseSolution
Forbidden403Account tier lacks quota APIUpgrade account tier
Unauthorized401Token expired/invalidRun --auth to refresh
Timeout-Network issuesCheck connectivity, increase timeout
Unprovisioned-Account not activatedSign into Gemini Code Assist in IDE first

​
Quota Shows 0% But Account Not Exhausted

Possible causes:
  • Quota not yet refreshed (30-second cache TTL)
  • All models at 0% (account exhausted)
  • Fetch returned null (treated as unknown)
Distinguish null vs 0:
  • null = fetch failed → shows “N/A”
  • 0 = quota exhausted → shows “0%”
Solution: 
# Force quota refresh with verbose
ccs cliproxy status --verbose

# Wait 30 seconds for cache to expire

​
Account Skipped in Rotation

Accounts are skipped when:
  1. Quota below threshold (default: 5%)
  2. Account is paused manually
  3. Account in cooldown (5 minutes after exhaustion)
  4. Quota fetch returned null
Check account status: 
ccs cliproxy status agy
Resume paused account: 
ccs cliproxy resume agy user@gmail.com

​
Common Problems

​
Claude CLI Not Found

Solution: Install from official documentation.

​
Permission Denied

chmod +x ~/.local/bin/ccs

​
Debug Mode

Enable verbose output: 
ccs --verbose glm
Shows:
  • Config file being read
  • Profile being selected
  • Settings file being used
  • Command being executed

​
Disable Colors

export NO_COLOR=1
ccs glm

​
Getting Help

  1. Check GitHub Issues
  2. Create new issue with:
    • Operating system
    • CCS version (ccs --version)
    • Exact error message
    • Steps to reproduce

​
Network Proxy Support

Available since v7.37.0 - CLIProxy respects standard proxy environment variables for network requests.
CCS and CLIProxy honor standard HTTP proxy environment variables for:
  • Binary downloads (CLIProxyAPI installation)
  • API requests to OAuth providers
  • Model catalog sync

​
Configuration

Set standard proxy environment variables: 
# HTTP proxy
export http_proxy="http://proxy.example.com:8080"

# HTTPS proxy
export https_proxy="http://proxy.example.com:8080"

# No proxy for specific hosts
export NO_PROXY="localhost,127.0.0.1,.internal"

​
Troubleshooting Proxy Issues

Connection failures behind proxy: 
# Verify proxy settings
echo $http_proxy
echo $https_proxy

# Test connectivity
curl -I https://api.gemini.google.com

# Enable debug mode
export CCS_DEBUG=1
ccs codex "test prompt"
Proxy authentication: Most proxies accept credentials in URL format: 
export http_proxy="http://username:password@proxy.example.com:8080"
SSL inspection/MITM proxies: If corporate proxy inspects SSL traffic, you may need to trust the proxy’s CA certificate: 
# Add CA certificate to system trust store
# Linux
sudo cp proxy-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# macOS
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain proxy-ca.crt

​
OAuth Callback Tracing

When an OAuth login fails (URL not displayed, callback never observed, token exchange error, etc.), CCS now emits branch-specific diagnostics instead of a generic “token not found” message. For deep debugging, enable the opt-in JSONL file sink: 
export CCS_OAUTH_LOG_FILE=1
ccs auth create work    # or any OAuth-triggering command
  • Log path: ~/.ccs/logs/oauth-YYYYMMDD.log (mode 0o600, rotated per day)
  • Format: JSONL, one event per line
  • Redaction: tokens, codes, and PKCE verifiers are stripped before write
  • Sinks: in-memory ring buffer (always on), verbose stdout (with CCS_DEBUG=1), file sink (opt-in via CCS_OAUTH_LOG_FILE=1)
Attach the log file when reporting OAuth issues — it contains per-phase timing (URL display, callback wait, token exchange, persistence) with secrets removed.