Troubleshooting & FAQ
Common questions and quick fixes. If your issue isn't here, check the container logs (docker compose logs -f api).
Installation & startup
The API container won't start.
Most often a configuration problem. The API refuses to boot if required secrets are missing or too short — JWT_SECRET must be ≥ 32 chars and admin_password ≥ 12 chars. Check docker compose logs api for a Missing secret or Invalid message. See the Configuration reference.
health reports degraded.
One of the dependencies is unreachable. The JSON shows which: database or opensearch. Confirm those containers are healthy (docker compose ps).
Browser warns about the certificate. Local deployments use a self-signed cert. Accept the warning for development, or install a real certificate for production — see TLS & certificates.
Login & access
I can't log in as the admin / I'm forced to change the password.
On first login the seed admin must change its password — this is expected. The initial value comes from the admin_password secret.
A user gets 403 editing a case they should be able to edit.
A USER can edit a case only if they created it or are assigned to it. Assign them (or check the assignee) — see users and roles.
Login for unknown usernames is slow. When LDAP is enabled, logins for non-existent users attempt a directory lookup and can be slower. Keep the LDAP connect timeout low. See the note in LDAP / AD auth.
Cases & data
I got a 409 Conflict updating a case. Someone else changed the case since you loaded it (optimistic concurrency). Re-fetch and re-apply your change — see Case lifecycle & concurrency.
Two related cases didn't link automatically. By design. Ticketra surfaces correlations but never auto-links — see the observable-centric model.
Search results look stale or missing. OpenSearch is a rebuildable secondary index; PostgreSQL is the source of truth. Recently-indexed items may lag briefly, and the index rebuilds from the database if needed. See Global search.
Integrations
A webhook returns 401. Wrong Basic-Auth credentials or the source is inactive. See Webhooks & SIEM.
No notifications arrive. For email, verify SMTP and run the SMTP Test; for Teams/Discord, confirm the webhook URL and that the channel is enabled. Check the notification log. See notifications.
CTI enrichment returns nothing for an internal IP. Private IPs are intentionally never sent to external providers.
Operations
How do I upgrade? Back up, then docker compose up -d --build; migrations run automatically. See Upgrades & migrations.
How do I recover from a bad upgrade? Restore the pre-upgrade backup — see Back up and restore.