Repository navigation
Troubleshooting
윤혁준 edited this page Jul 10, 2026
·
3 revisions
Start by narrowing the symptom. Do not copy tokens, passwords, connection strings, or keys into command output or support requests.
| Symptom | Check | Safe next action |
|---|---|---|
Compose stops with an AUTH_SECRET error |
Confirm that the deployment environment provides AUTH_SECRET. |
Generate and retain a secret in the deployment environment or .env before starting Compose. Do not rotate it casually: changing it invalidates existing sessions. |
| Port 3000 is already in use | Identify the existing listener or choose an unused host port. | Start Compose with an approved alternative, such as PORT=3100 docker compose up -d. |
/api/health works but /api/ready fails |
Run docker compose ps -a and inspect docker compose logs postgres migrate. Check external database reachability if used. |
Wait for Postgres and migration completion, then correct the deployment configuration or database connectivity issue. Do not modify the production database directly. |
| The first administrator cannot sign in | Check whether /setup was completed or whether the intended bootstrap variables were present before the first migration. |
Use the documented seed profile with administrator values supplied through the deployment environment, then sign in. Do not disclose the password in a ticket or shell history. |
| No events arrive after shim installation | Run toard-shim doctor, then toard-shim collect --dry-run. Verify the endpoint is the server URL plus /api, the token is active, and /api/ready returns 200. |
Correct the local credentials through the normal installation flow and run toard-shim collect. For Desktop or IDE use, install the scheduled collector. |
| Desktop or IDE usage appears late | Check toard-shim daemon status. Wrapper-triggered collection may not run for tools that bypass PATH. |
Run toard-shim daemon install; it schedules one-shot collection without a permanent shim process. |
| Content history is unavailable | Confirm that the server has a content KEK, the user opted in, and a remote endpoint uses HTTPS. | Enable content collection only after reviewing Privacy and security. A first opt-in collects from that point forward by default. |
Costs display as $0
|
In Admin → System, check the pricing sync status and whether PRICING_AUTO_SYNC=off is intentional. |
Run a manual pricing sync from the admin UI. If an external scheduler is used, verify its protected request configuration without printing CRON_SECRET. |
| An external cron call returns 401 | Confirm that the deployment has CRON_SECRET and that the caller supplies the matching Bearer authorization. |
Fix the scheduler's secret reference and retry. Keep the value out of logs and command history. |
| The installer advertises the wrong endpoint behind a proxy | Compare the browser URL with the actual ingestion URL. | Set TOARD_PUBLIC_URL to the pathless public http or https origin, restart the app, and re-check the generated install command. |
| Shim update fails or is unsuitable for the network | Run toard-shim version; check whether a mirror or air-gapped release policy is in use. |
Use toard-shim update, or configure TOARD_SHIM_RELEASE_BASE for the approved mirror. Do not disable checksum verification. |
| ClickHouse rollup totals do not match | Keep CLICKHOUSE_READ_ROLLUP off and inspect duplicate rows, outbox backlog, and raw-versus-rollup differences. |
Continue with the raw query path and follow the exact rollup runbook before enabling rollup reads. |
For a deployment problem, gather the symptom, the health/readiness response, container status, and redacted logs. For a suspected vulnerability, do not use a public issue; use the private security advisory flow.
Never use docker compose down -v as a troubleshooting shortcut: it removes volumes. Likewise, do not run destructive SQL or reset a production database to diagnose a service issue. The deployment guide is the canonical platform runbook.