Troubleshooting
Start with the backend log (docker compose logs cotracer-backend or
kubectl logs deploy/cotracer) and /healthz — most problems name themselves
there.
Registry
Section titled “Registry”docker login fails / unauthorized — the token was revoked, expired, or
rotated more than 7 days ago. Generate a new one on the Downloads page. The
username is partner-org_…, not your email.
no matching manifest for linux/… — use version 0.1.1 or newer (amd64 and
arm64).
CLI install: … was not found in the package registry / 403 — you used the
registry as a package index. Download the wheel file and install it instead
(Install → CLI).
Kubernetes ImagePullBackOff — the cotracer-registry pull secret holds an
old token. Recreate it after every rotation.
License
Section titled “License”/healthz → license.state:
| State | Fix |
|---|---|
missing |
set COTRACER_LICENSE_TOKEN or mount /app/cotracer-license.jwt |
invalid |
the file or token is corrupted or not from Cotracer — re-download / regenerate |
expired |
renew the subscription or pilot; with a token, the backend picks up the new license within a day (restart to pick it up now) |
expiring |
fewer than 14 days left — works, but act now |
Analyses return 402 while the license is not usable, and 403 when your
plan lacks the feature (e.g. local developer analyses). The backend can’t reach
platform.cotracer.ai? It keeps the last fetched license; check HTTPS_PROXY.
Startup
Section titled “Startup”Exits immediately with a config error — cotracer.yaml is missing or has an
unknown key; the message names it. Unknown keys are rejected on purpose.
llm.api_key_env names '…' but that env var is not set — add the key to
.env / the Secret and restart.
GitHub errors (401/404) during an analysis — App id or key wrong, vcs.org
not set, or the App isn’t installed on the org / that repo. For Compose, the private key must be on one line with
\n escapes (Connect GitHub).
Analyses
Section titled “Analyses”Report misses a service you know depends on the change — check the GitHub App is installed on that repo, and that the dependency shows up in your traces in the last few hours. Services with no trace edges (batch jobs, shared-library consumers) are only found through code search.
read_logs / tracing “Could not connect” — the backend can’t reach the URL
in cotracer.yaml. Use the in-network service name, not localhost, when the
backend runs in a container.
Slow or truncated output through an ingress / proxy — the CLI streams over SSE; disable proxy buffering and raise the read timeout.
CLI: 401 invalid or missing API key — COTRACER_API_KEY on the client
doesn’t match the backend’s.
Exit 2 in CI — the step log says which: backend unreachable from the runner, license (402/403), or the model ended without a report. The check fails closed by design.
Still stuck? Send the backend log and /healthz output to your Cotracer
contact.