Troubleshooting

The container won't start

docker compose ps shows it cycling between Restarting and Exited. The usual cause is the startup security check: published images refuse to start while a placeholder or weak secret, or a well-known admin password, is configured. The log opens with Refusing to start: insecure configuration and names each problem.

That is typically an .env copied from an older example. Delete those lines — the container then generates the values on first boot — or set real ones with openssl rand -hex 32. If the install already stored credentials, keep its existing TALON_ENCRYPTION_KEY: a new one cannot decrypt them, or your Talon key.

Without that block, the entrypoint printed one of these before the app ever started:

The page won't load

The container is Up, but the browser or your load balancer cannot reach it, or reports it unhealthy. Three endpoints tell you which layer is failing:

Docker does not restart a container for being unhealthy; it only marks it. The logs are where the answer is.

A migration fails

The container exits with Migration failed in the log, just after Running database migrations. Migrations run on every start, before the app; a failure stops the entrypoint, and the restart policy retries — skipping what already applied. The error above that line is the real one. The usual causes:

If it cannot be fixed in place, stop booting forward: pin the previous tag and restore the pre-upgrade backup — Upgrading → Rolling back.

Stuck on the key screen

Every page opens on the License page, and the API answers 403 licence_required. The reason on that page says which of these it is:

Nothing is deleted while the key screen is up: agents and outgoing notifications pause, and syncs keep running. An Enterprise key that expires or is revoked never causes this — it returns the instance to the Community Edition instead. Licensing has the whole table.

pySigma is unavailable

Sigma translation or validation fails in Forge or Validate with Sigma service unavailable, or /api/health reports sigma: error. pySigma runs inside the container on 127.0.0.1:8001, and readiness counts it, so the whole appliance reads not_ready while it is down — though anything that reads stored data (detections, the library, SOC, Connect, coverage) still works.

Nothing restarts pySigma on its own if it dies mid-run; docker compose restart brings it back. If it never comes up at boot, the log around Starting embedded pySigma service has the Python error.

The content library stays empty

SigmaHQ, Splunk Security Content, Atomic Red Team and the rest never populate, or stop updating, and Settings → App Logs shows sync failed under content-sync. The sync clones those repositories at startup and then hourly; on a network that cannot reach GitHub, every attempt fails.

It never blocks startup or crashes the app — it logs and tries again next hour — but content.last_synced in /api/health?detailed=1 stops moving and the detailed status reads degraded. Point the sources at internal mirrors, or turn the sync off: Offline and air-gapped has both.

Locked out

Before you ask for help

There is no one-click support bundle yet. Collect these:

Add your docker-compose.yml and .env with every secret removed, and the exact log lines around the failure — the format (<time> LEVEL [context] event - key=value) is meant to be pasted. Send them through the contact form.