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:

Restart your terminal
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

Windows
macOS/Linux

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

echo 'export CCS_CLAUDE_PATH="/opt/custom/claude"' >> ~/.bashrc
source ~/.bashrc

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:

Check connectivity:

curl https://cloudcode-pa.googleapis.com

Run diagnostics with verbose mode:

ccs cliproxy status --verbose
ccs agy --verbose

Verify account tier: Some free-tier accounts don’t have quota API access. Upgrade to paid tier if needed.
Refresh authentication:

ccs agy --auth

Quota Fetch Error Codes

Error	HTTP Status	Cause	Solution
Forbidden	403	Account tier lacks quota API	Upgrade account tier
Unauthorized	401	Token expired/invalid	Run `--auth` to refresh
Timeout	-	Network issues	Check connectivity, increase timeout
Unprovisioned	-	Account not activated	Sign 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:

Quota below threshold (default: 5%)
Account is paused manually
Account in cooldown (5 minutes after exhaustion)
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

Check GitHub Issues
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"