Troubleshooting

Run docker compose logs authme to see the startup error.

Ensure DATABASE_URL is set and the PostgreSQL container has finished initialising (add a healthcheck).

Confirm the PostgreSQL port (5432) is not blocked by another process.

Verify DATABASE_URL matches your PostgreSQL host, port, user, and database name.

When running with Docker Compose, use the service name as hostname (e.g. postgresql://authme:authme@db:5432/authme).

Run npm run prisma:migrate if this is a fresh install.

SMTP is configured per-realm in the Admin Console under the Email tab — not via environment variables.

Use the Test Email button to verify connectivity.

Check that your SMTP provider allows connections from your server IP, and that the port/TLS settings match (587 with STARTTLS is most common).

Ensure BASE_URL is set to your exact public URL (no trailing slash).

Register your frontend origin as an allowed redirect URI on the OIDC client.

In the Admin Console, verify the Web Origins field on the client includes your frontend URL or * for development.

Confirm the issuer in your SDK config matches the exact issuer in the AuthMe discovery document.

Check that the token has not expired (exp claim). Tokens are short-lived by default (5 minutes).

Rotate the signing keys only when necessary — old tokens signed with rotated keys will fail validation.

Verify the LDAP host, port, and bind DN are correct in the realm's Identity Provider settings.

Test connectivity from inside the AuthMe container: docker exec -it authme_app ping ldap-host.

Check that your LDAP server supports the connection type selected (LDAP on 389 or LDAPS on 636).

Themes are configured per-realm in the Admin Console under the Appearance tab.

Clear your browser cache after changing a theme — the CSS bundle is heavily cached.

Ensure the realm is saved after selecting the new theme.

Run npm run prisma:migrate manually after pulling a new version.

If a migration is stuck, check for a _prisma_migrations row with applied = false and resolve any conflicts.

Always back up your database before upgrading to a new major version.

Scale horizontally: add more AuthMe replicas behind the Nginx load balancer (see the Deployment guide).

Add a pg_bouncer connection pooler in front of PostgreSQL to reduce connection overhead.

Tune THROTTLE_TTL and THROTTLE_LIMIT to prevent a single client from dominating.

Set NODE_ENV=production to suppress debug-level logs automatically.

To increase verbosity temporarily, set LOG_LEVEL=debug in your environment.

Pipe logs to a structured aggregator (Loki, Datadog, CloudWatch) using Docker's log driver.