> ## 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 solutions

# Troubleshooting

Common issues and their solutions.

<Note>
  For detailed error code reference and recovery strategies, see [Error Codes](/reference/error-codes).
</Note>

## 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**:

```bash theme={null}
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**:

```powershell theme={null}
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### Claude CLI Not Found

```powershell theme={null}
where.exe claude
```

If missing, install from [Claude docs](https://docs.claude.com/en/docs/claude-code/installation).

## Claude CLI in Non-Standard Location

### Set CCS\_CLAUDE\_PATH

<Tabs>
  <Tab title="Windows">
    ```powershell theme={null}
    $env:CCS_CLAUDE_PATH = "D:\Program Files\Claude\claude.exe"
    [Environment]::SetEnvironmentVariable("CCS_CLAUDE_PATH", $env:CCS_CLAUDE_PATH, "User")
    ```
  </Tab>

  <Tab title="macOS/Linux">
    ```bash theme={null}
    echo 'export CCS_CLAUDE_PATH="/opt/custom/claude"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>
</Tabs>

## Configuration Issues

### Profile Not Found

**Error**: `Profile 'foo' not found in ~/.ccs/config.yaml`

**Solution**: Add profile to config:

```yaml theme={null}
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:

```yaml theme={null}
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:**

```bash theme={null}
curl https://cloudcode-pa.googleapis.com
```

2. **Run diagnostics with verbose mode:**

```bash theme={null}
ccs cliproxy status --verbose
ccs codex --verbose
```

3. **Verify account tier:**
   Some free-tier accounts don't have quota API access. Upgrade to paid tier if needed.

4. **Refresh authentication:**

```bash theme={null}
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:**

```bash theme={null}
# 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:**

```bash theme={null}
ccs cliproxy status agy
```

**Resume paused account:**

```bash theme={null}
ccs cliproxy resume agy user@gmail.com
```

## Common Problems

### Claude CLI Not Found

**Solution**: Install from [official documentation](https://docs.claude.com/en/docs/claude-code/installation).

### Permission Denied

```bash theme={null}
chmod +x ~/.local/bin/ccs
```

## Debug Mode

Enable verbose output:

```bash theme={null}
ccs --verbose glm
```

Shows:

* Config file being read
* Profile being selected
* Settings file being used
* Command being executed

## Disable Colors

```bash theme={null}
export NO_COLOR=1
ccs glm
```

## Getting Help

1. Check [GitHub Issues](https://github.com/kaitranntt/ccs/issues)
2. Create new issue with:
   * Operating system
   * CCS version (`ccs --version`)
   * Exact error message
   * Steps to reproduce

## Network Proxy Support

<Note>Available since v7.37.0 - CLIProxy respects standard proxy environment variables for network requests.</Note>

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:

```bash theme={null}
# 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:**

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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.