Work through symptoms top to bottom. Capture docker compose logs excerpts when opening an internal incident.

Container exits immediately: invalid environment

Symptom: payload-app restarts loop; logs mention Zod or "Invalid environment variables".

Checks:

1. Compare your .env against apps/dashboard/.env.example.
2. Confirm DATABASE_URI, REDIS_URI, PAYLOAD_SECRET, and NEXT_PUBLIC_WEBSITE_URL are set and reachable from the container.
3. See DOCKER.md for build-time vs runtime validation.

Cannot reach the dashboard

Symptom: Browser timeout or connection refused.

Checks:

1. docker compose ps: are traefik and payload-app healthy?
2. Firewall: 80 / 443 open to Traefik?
3. NEXT_PUBLIC_WEBSITE_URL matches the hostname clients use.
4. If behind another proxy, verify upstream routing and WebSockets.

TLS or ACME failures

Symptom: Certificate warnings or Traefik ACME errors.

Checks:

1. acme.json exists and is writable (chmod 600).
2. CF_DNS_API_TOKEN (or other DNS API creds) still valid.
3. DNS records point to this host before ordering certs.
4. More context: Control plane domains and SSL.

MongoDB auth errors

Symptom: App logs show authentication failed against mongodb.

Checks:

1. MONGO_INITDB_ROOT_USERNAME / MONGO_INITDB_ROOT_PASSWORD match DATABASE_URI.
2. You did not re-create the mongo-data volume with new creds without resetting the database.
3. Network: payload-app resolves hostname mongodb.

Redis connection errors

Symptom: Queue or cache errors referencing redis.

Checks:

1. redis container running.
2. REDIS_URI uses the Compose service name (e.g. redis://redis:6379).

Tailscale-related failures

Symptom: Features that expect tailnet integration stay disabled or error.

Checks:

1. NET_ADMIN and /dev/net/tun still on payload-app.
2. TAILSCALE_AUTH_KEY, TAILSCALE_OAUTH_CLIENT_SECRET, and TAILSCALE_TAILNET populated and not expired.
3. Separate Worker Node mesh issues: Compute and worker node issues under Troubleshooting in the sidebar.

Beszel agent spam or crashes

Symptom: beszel-agent logs errors about auth.

Checks:

Replace placeholder KEY and TOKEN in docker-compose.yml or disable the agent service until configured.

Still stuck

• Troubleshooting overview under Troubleshooting in the sidebar
• Getting started issues under Troubleshooting in the sidebar (first-login class problems)
• When to contact support under Troubleshooting in the sidebar (expectations for self-hosted)