Self-hosting troubleshooting

Common control-plane failures when self-hosting dFlow and what to check next.

Written By Zoro

Last updated 25 days ago

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)