Skip to main content
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.

​
Session Management Issues

​
Error: SESSION_ACTIVE

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

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

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.