Troubleshooting

This page helps with issues when self-hosting NetBird. Collect the diagnostics below, then pick the area that matches your problem.

Start here

Collect diagnostics first

Almost every self-hosted issue is faster to resolve with service status and logs in hand. Grab these before you go deeper.

1. Check services

Service status

docker compose ps

Are management, signal, relay, and the dashboard all Up?

2. Read the logs

Service logs

docker compose logs -f management

Most config, auth, and migration errors surface here.

3. Test reachability

Proxy to API

curl -v https://YOUR_DOMAIN/api/health

Confirms the reverse proxy can reach the Management API.

Each area lives on its own page. Pick the one closest to your problem.

The getting-started script: the readiness wait, DNS, certificates, Traefik, and re-running cleanly.

Setup page access, SSO connectors, redirect URIs, and users syncing from your provider.

Blank pages and unauthorized or 403 errors in the self-hosted dashboard.

Let's Encrypt renewal and TLS errors behind a custom reverse proxy.

Testing the TURN server, peer-to-peer failures, and an unreachable Management service.

The Management service failing to start after an upgrade, and recovery after power loss.

If you're still experiencing issues, see Report bugs and issues for the right channel:

Gather evidence first: docker compose logs for all services, your configuration (without secrets), and the steps to reproduce.
Open source self-hosted and general questions go to Community Support: the Slack Channel for quick questions, or GitHub Discussions for a written record.
Cloud customers and users, and commercial-license deployments can reach the team through NetBird Support.