Troubleshooting

"The dashboard is empty even though my agent made requests"

Check that your agent is actually hitting the proxy, not the upstream provider directly. The simplest way: curl http://localhost:8080/v1/models and confirm it returns a JSON list of models configured in your .env.

If the request is reaching the proxy but not being recorded, the most common cause is the x-acg-project header missing. Without a project tag, the request is still recorded but it lands in the "untagged" bucket, which the dashboard hides by default. Toggle "Show untagged" in the project picker.

"My agent is being auto-stopped mid-task"

This is the gateway working as designed. Two options:

Raise the budget for that project in the dashboard. The new ceiling takes effect immediately.
Disable auto-stop for that project and rely on alerts only. The auto-stop column on the project list has a one-click toggle.

We do not recommend disabling auto-stop globally. The default of "stop the request rather than wake up to a $500 bill" is the right one.

"I'm getting 401 from the upstream provider"

ai-cost-gate forwards the Authorization header from the upstream credential you set in .env, not the one your client sends. If you see a 401:

Check UPSTREAM_OPENAI_API_KEY is set and starts with sk-.
Confirm the key has access to the model you requested. Some models require a specific project or org.
Check upstream status: https://status.openai.com/.

"SQLite database is locked"

Only one process can write to the SQLite file at a time. If you're seeing this, you probably have two ai-cost-gate instances pointing at the same file. Stop one.

"I can't access the dashboard"

The default bind is 0.0.0.0:3000. If you can't reach it:

Check LISTEN_HOST and LISTEN_PORT in your env.
If you're behind Docker, make sure port -p 3000:3000 is set.
If you're behind nginx/Caddy, check your reverse proxy logs for the actual error.

"The dashboard is slow"

Almost always: a large generation_history table. Run the bundled cleanup:

docker exec ai-cost-gate aicg cleanup --older-than 30d

This deletes request rows older than 30 days. Cost totals in attribution are kept.