Skip to main content

​
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.json
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.json 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: 
{
  "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 agy --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 agy --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