Troubleshooting
Updated
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 psAre netbird-server and dashboard Up, plus traefik if you chose the built-in Traefik? Installs from before v0.65.0 run separate management, signal, and relay services instead.
2. Read the logs
Service logs
docker compose logs -f netbird-serverMost config, auth, and migration errors surface here. On installs from before v0.65.0, read the management service logs.
3. Test reachability
Proxy to API
curl -s https://YOUR_DOMAIN/api/instanceA JSON reply with setup_required confirms the reverse proxy can reach the Management API.
Find your issue by area
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.
Checking the relay, peer-to-peer failures, and an unreachable Management service.
The Management service failing to start after an upgrade, and recovery after power loss.
Getting Help
If you're still experiencing issues, see Report bugs and issues for the right channel:
- Gather evidence first:
docker compose logsfor 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.