Troubleshooting a failed startup

If MobilityManager fails to start or never becomes ready, the cause is usually a missing secret, a database it cannot reach, or a misconfigured provider. This article maps the most common failures to their fixes.

Start with the logs and health endpoints

1. Read the container or process logs for the first error — startup checks fail fast with a clear message.
2. Check the health endpoints:

   curl -i http://localhost:8080/livez
   curl -i http://localhost:8080/readyz

A liveness pass with a readiness failure points to a dependency problem (typically the database) rather than a crash.

The JWT key is missing or weak

Symptom: startup throws an error that Jwt:Key must be a strong (≥32 byte) secret and must not be a committed default.

Fix: set Jwt__Key to a fresh random value of at least 32 bytes that is not one of the example keys. In Docker Compose this is JWT_KEY; in Kubernetes it is a Secret entry.

The document encryption key is missing

Symptom: startup throws an error that DocumentStorage:EnableEncryptionAtRest is on but DocumentStorage:LocalEncryptionKey is not configured.

Fix: provide a base64-encoded 32-byte key in DocumentStorage__LocalEncryptionKey, or set DocumentStorage__EnableEncryptionAtRest=false if you do not need encryption.

The database provider is invalid

Symptom: an Unsupported database provider error.

Fix: set DatabaseProvider to exactly PostgreSQL or SqlServer. The value is case-sensitive.

The app starts but redirects everyone to /setup

Symptom: the application starts and stays healthy but every page redirects to the setup wizard.

Cause: the system is not yet configured, or the app is running against the in-memory fallback database because the connection strings or provider are missing.

Fix: confirm DatabaseProvider and both connection strings are set and reachable, then complete onboarding. The app is "configured" only once it has a user, an active license, and a tenant.

Note: Migrations are skipped — not failed — when the database is unreachable at startup. Look for a warning about applying migrations and using the onboarding wizard, and fix connectivity rather than the migration itself.

The database is unreachable

• Verify the host, port, database name, username, and password in the connection string.
• Confirm the connection-string format matches the provider (Npgsql for PostgreSQL, Server/Initial Catalog for SQL Server).
• Check network policy and that the database container or service is healthy.
• For SQL Server, confirm Encrypt and certificate trust settings are compatible with your server.

Clock tampering aborts startup

Symptom: a critical log entry states clock tampering was detected and startup was aborted.

Fix: the system clock appears to have moved backwards relative to the license record. Restore the correct system time and restart.

Related

• Setting the JWT signing key for production
• Configuring the document encryption-at-rest key
• Configuring the database connection strings
• Understanding the health endpoints