Troubleshooting

A look at the logs helps first almost every time:

docker compose ps
docker compose logs --tail 100 <service>

Error messages in the web UI are generic; the details are in the log under the same correlation ID.

Installation and start

Problem	Cause and solution
A service does not start and names an unsafe setting	A secret is given directly in the environment instead of as a file, or a required value is missing. The message names the setting, never the value.
migrate ends with an error	The database cannot be reached or a secret is missing. ../../scripts/generate-secrets.sh creates missing secrets, then docker compose up -d postgres and docker compose run --rm migrate.
Sign-in fails with error 500 after an interrupted start	Containers with missing network aliases. docker compose up -d --force-recreate creates them again.
Start refused because of an unencrypted connection	PostgreSQL or Valkey are on another host without TLS. See High availability.
Ports 80 or 443 are not available	Rootless Docker or Podman may not open low ports, see Installation.
No certificate is issued	For ACME, ports 80 and 443 must be reachable from the internet and the DNS names must point to the server. In an internal network set SA_UI_TLS=internal.

Sign-in

Problem	Cause and solution
OIDC sign-in is refused	No group of the account matches the mapping, or the claim is not called groups. Check the mapping under Settings › Sign-in.
Identity provider not reachable	docker compose run --rm cli admin disable-oidc; the emergency access applies again.
Emergency account locked or authenticator lost	docker compose run --rm cli admin reset-totp --username <name>
Session ends unexpectedly	Every session ends after 30 minutes idle or 12 hours. A deactivated account loses its session at the next renewal.

Agents and collector

Problem	Cause and solution
“Server not reachable” at enrolment	DNS, routes or a firewall between device and server. The message names host and port.
Enrolment stops because of the CA	The fingerprint in the command does not match the root CA, or a proxy breaks TLS open. Exempt the agent host from TLS inspection.
Token refused	expired, used up or revoked. Create a new one.
Agent does not appear as an asset	It waits for approval under Agents. Without approval it is blocked after the period.
Agent stops reporting	Certificate expired (check the device’s clock) or agent blocked. A blocked agent needs a new rollout token.
Collector finds no MAC addresses	It is in another network segment.

Uploads and documents

Problem	Cause and solution
File too large	Limit SA_DOCUMENT_MAX_BYTES, 25 MiB by default. A proxy in front may have a smaller limit of its own; the web UI then names it as the cause.
Upload refused, scanner not reachable	A virus scanner is set but does not run. docker compose --profile scanner up -d.
Storage full	The sum of all versions per organisation is limited (SA_DOCUMENT_QUOTA_BYTES).
A BSI catalogue cannot be imported	The file is larger than 16 MiB, or a proxy in front limits the size.

Outgoing connections

Notifications, directory service, AI assistant and connectors reach only networks you allow. A target in your own network needs the matching variable, such as SA_NOTIFICATION_ALLOWED_NETWORKS=public,192.168.10.5/32 (Configuration). Targets need TLS 1.3 and a valid certificate; for an own CA, add its certificate to the connection.

System health

The page System health shows whether database, Valkey, job worker and virus scanner answer. If a job waits long past its time, the worker is probably not running: docker compose logs worker.