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

Codex config.toml Cannot Be Parsed

If Codex writes a model migration and joins it to the next TOML table header, the Control Center disables structured controls to avoid overwriting the invalid file. Solution: Open ccs config, select Codex config.toml, then choose Preview one-newline repair. CCS creates an unsaved editor draft that inserts only the missing newline. Review the diff and select Save to write it. The save uses the file version observed when the draft was created, so it refuses a concurrent change instead of overwriting it. The preview appears only for this exact migration-table boundary. For any other TOML error, correct the raw TOML manually and save it after the validation message clears.

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 codex --verbose

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

ccs codex --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"