> ## Documentation Index
> Fetch the complete documentation index at: https://costhq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting & Common Issues

> Solutions to common errors, proxy issues, and missing costs when using CostHQ.

If you run into issues while using CostHQ, check the common scenarios below. If your problem isn't listed, feel free to open an issue on the [GitHub repository](https://github.com/brian-mwirigi/CostHQ).

## Session Management Issues

### Error: `SESSION_ACTIVE`

```text theme={null}
Error: An active session already exists for this directory.
```

**Why it happens:** You tried to run `cs start` or `cs run` in a Git repository (or directory) that already has an active session running.

**How to fix it:**

* If the session is legitimately still running and you want to resume it, use `cs start --resume`.
* If an agent crashed and left the session "orphaned" (stale), use `cs start --close-stale` to automatically end the old one and start a new one.
* To just close the active session without starting a new one, run `cs end`.

### Error: `NO_ACTIVE_SESSION`

```text theme={null}
Error: No active session found. Run cs start first.
```

**Why it happens:** You tried to run `cs log-ai`, `cs note`, or `cs end`, but CostHQ couldn't find an active session scoped to your current directory or Git root.

**How to fix it:**
Start a session first with `cs start "Task Name"`. If you are trying to log to a specific session that isn't the active one for your current directory, pass the session ID explicitly: `cs log-ai ... -s <id>`.

## Cost and Pricing Issues

### Costs are showing as \$0.00

**Why it happens:** You logged AI usage for an unknown model, and CostHQ didn't know how much to charge for it.

**How to fix it:**

1. Check if the model is in the built-in pricing table: `cs pricing list`.
2. If it is a cloud API model, set a custom price for it: `cs pricing set <model> <input-price> <output-price>`. Future calls will calculate automatically.
3. If it is a **local model** running on your GPU (e.g. Ollama, vLLM), register its hourly compute rate: `cs local-models add <provider>/<model> --cost-per-hour <rate>` and log its usage using the `--duration` flag.
4. Or, pass the exact cost manually when logging: `cs log-ai -p custom -m custom -t 1000 -c 0.05`.

### CostHQ Proxy isn't capturing traffic

**Why it happens:** The CostHQ proxy is running, but your agent or script isn't routing its API calls through the proxy port.

**How to fix it:**
CostHQ proxy runs on `http://127.0.0.1:3739` by default. You need to tell your tools to use it:

* Set standard environment variables: `export HTTP_PROXY=http://127.0.0.1:3739` and `export HTTPS_PROXY=http://127.0.0.1:3739`.
* If using Node.js, ensure `GLOBAL_AGENT_HTTP_PROXY` is set, or configure your specific SDK (like `openai` or `anthropic`) to use a custom `baseURL`.

## Dashboard and Server Issues

### Error: `EADDRINUSE: address already in use`

```text theme={null}
Error: listen EADDRINUSE: address already in use :::3739
```

**Why it happens:** CostHQ tried to start the proxy or the dashboard server, but the port is already taken by another application (or an orphaned CostHQ process).

**How to fix it:**

* Start CostHQ on a different port: `cs dashboard --port 4000` or `cs proxy --port 3740`.
* Or, find and kill the process using the default port (3739 for proxy, 3738 for dashboard). On macOS/Linux: `lsof -i :3739` then `kill -9 <PID>`.

## File Tracking Issues

### CostHQ isn't detecting my file changes

**Why it happens:** The background file watcher might not be running, or your files are ignored.

**How to fix it:**

* Ensure you started the session with `cs start` or `cs run`. The watcher starts automatically in the background.
* CostHQ respects `.gitignore`. If a file is git-ignored, CostHQ won't track changes to it.
* To check watcher status, run `cs status` — it should indicate if the background watcher is active.

## Enterprise / Pro License Issues

### Error: `Audit trail requires an Enterprise license`

**Why it happens:** You tried to run a `cs audit` command or access an enterprise endpoint without an active Enterprise-tier license.

**How to fix it:**
Add your license key using `cs dashboard` (Settings page) or via the environment. Ensure your license plan is `enterprise` and not `pro`. You can verify your license status in the dashboard.