Skip to main content
This guide helps you diagnose and resolve common issues with NetBird deployments.

​
Quick Diagnostics

​
Check Client Status

# Basic status
netbird status

# Detailed peer status
netbird status --detail

# JSON output for parsing
netbird status --json

​
Generate Debug Bundle

Create a comprehensive debug package with logs and system info: 
# Basic debug bundle
netbird debug bundle

# Include system information
netbird debug bundle --system-info

# Include multiple log files (rotated logs)
netbird debug bundle --log-file-count 3

# Anonymize sensitive data
netbird debug bundle --anonymize
The bundle includes:
  • Client logs
  • System information
  • Current status
  • Network configuration
  • Peer connection details
Debug bundles are saved as .tar.gz files in your current directory.

​
Run Timed Debug Session

Capture detailed logs for a specific duration: 
# Run with trace logging for 5 minutes
netbird debug for 5m

# For shorter duration
netbird debug for 30s
This automatically:
  1. Sets log level to trace
  2. Restarts the connection
  3. Runs for the specified time
  4. Creates a debug bundle
  5. Restores original settings

​
Connection Issues

​
Peer Not Connecting

1

Check daemon status

# Linux/macOS
systemctl status netbird

# Windows (PowerShell)
Get-Service Netbird

# Or use NetBird CLI
netbird status
2

Verify network reachability

# Check if you can reach the peer's public IP
netbird status --detail

# Look for connection type (P2P vs Relayed)
# Status should be "Connected", not "Idle"
3

Check firewall rules

# Linux - verify WireGuard port is open
sudo ufw status
sudo iptables -L -n | grep 51820

# Check if WireGuard interface exists
ip addr show wt0  # or wg0, nb0 depending on config
4

Test with increased logging

netbird debug log level trace
netbird down
netbird up
# Check logs for connection attempts

​
NAT Traversal Failures

If peers can’t establish direct P2P connections:
  • Connections show as “Relayed” instead of “P2P”
  • High latency between peers
  • netbird status --detail shows relay connection type
# Check connection types
netbird status --filter-by-connection-type Relayed

# Look for ICE negotiation in logs
grep "ICE" /var/log/netbird/client.log
grep "STUN" /var/log/netbird/client.log
  1. Verify STUN/TURN servers are accessible: 
    # Test STUN connectivity
nc -zvu stun.netbird.io 3478
  2. Check symmetric NAT:
    • Symmetric NAT prevents direct P2P
    • Relay connection is expected behavior
  3. Configure external IP mapping: 
    # If behind NAT with known public IP
netbird up --external-ip-map 12.34.56.78/10.0.0.1
  4. Open WireGuard port (51820/UDP): 
    # Linux UFW
sudo ufw allow 51820/udp

# iptables
sudo iptables -A INPUT -p udp --dport 51820 -j ACCEPT
  5. Verify relay server is running: 
    curl http://relay.netbird.io:8080/health

​
Authentication Failures

Error: status: StatusSessionExpired or StatusLoginFailedSolution:
# Re-login with SSO
netbird down
netbird up

# Or with setup key
netbird up --setup-key YOUR_SETUP_KEY
Error: failed to connect to management serverDiagnosis:
# Test connectivity
curl -k https://api.netbird.io:443/api/peers

# Check DNS resolution
dig api.netbird.io

# Test with custom URL
netbird up --management-url https://your-management-server.com
Solutions:
  • Check firewall allows outbound HTTPS (443)
  • Verify DNS resolution
  • Check management server is running: docker compose ps management
  • Verify certificate validity
Error: Authentication redirects fail or timeoutCheck:
# Management server logs
docker compose logs management | grep -i "idp\|auth"

# Look for IDP metrics
curl http://localhost:9090/metrics | grep idp_request_error
Common causes:
  • Incorrect IDP configuration in management.json
  • Network can’t reach IDP endpoints
  • IDP credentials expired or invalid

​
DNS Issues

​
NetBird DNS Not Resolving

1

Check DNS configuration

# Verify NetBird DNS is configured
netbird status --detail

# Check resolver address
cat /etc/resolv.conf | grep netbird
2

Test DNS resolution

# Try resolving a peer name
nslookup peer-a.netbird.cloud
dig @100.64.0.1 peer-a.netbird.cloud
3

Configure custom DNS resolver

# Set specific DNS resolver address
netbird up --dns-resolver-address 127.0.0.1:5053

# Clear DNS configuration
netbird up --dns-resolver-address ""

​
DNS Resolution Conflicts

NetBird DNS may conflict with existing local DNS services on port 53.
# Check what's using port 53
sudo lsof -i :53
sudo netstat -tulpn | grep :53

# Use custom DNS port
netbird up --dns-resolver-address 127.0.0.1:5053

​
Performance Issues

​
High Latency

# Verify using P2P when possible
netbird status --detail

# If showing "Relayed", see NAT Traversal section
# Relay adds latency due to extra hop

# Test peer latency
ping -c 10 100.64.0.5  # Use peer's NetBird IP

# Check for packet loss
mtr 100.64.0.5

# Verify WireGuard stats
sudo wg show
Incorrect MTU can cause fragmentation and poor performance:
# Test with custom MTU
netbird up --mtu 1280

# Default WireGuard MTU is 1420
# Lower if seeing fragmentation issues

​
High CPU Usage

1

Check active connections

netbird status --detail
# Count number of connected peers
2

Profile CPU usage

# Enable CPU profiling during debug session
netbird debug for 2m
# Profile is included in debug bundle
3

Optimize connection settings

# Enable lazy connections (on-demand)
netbird up --enable-lazy-connection

# This reduces idle peer connections

​
Service Issues

​
Service Won’t Start

# Check service status
systemctl status netbird

# View recent logs
journalctl -u netbird -n 50

# Check for service file issues
systemctl cat netbird

# Reinstall service
netbird service stop
netbird service uninstall
netbird service install
netbird service start

# Check service status
Get-Service Netbird

# View event logs
Get-EventLog -LogName Application -Source Netbird -Newest 20

# Reinstall service
netbird service stop
netbird service uninstall
netbird service install
netbird service start

# Check launchd service
sudo launchctl list | grep netbird

# View logs
log show --predicate 'process == "netbird"' --last 1h

# Restart service
sudo launchctl unload /Library/LaunchDaemons/io.netbird.client.plist
sudo launchctl load /Library/LaunchDaemons/io.netbird.client.plist

​
Configuration File Issues

1

Locate config file

# Linux
/etc/netbird/config.json

# Windows
C:\ProgramData\Netbird\config.json

# macOS
/etc/netbird/config.json
2

Validate JSON

# Check for syntax errors
cat /etc/netbird/config.json | jq .
3

Reset configuration

# Backup existing config
sudo cp /etc/netbird/config.json /etc/netbird/config.json.bak

# Login creates fresh config
netbird down
netbird up --setup-key NEW_KEY

​
Server Issues

​
Management Server Not Starting

1

Check container status

docker compose ps
docker compose logs management
2

Verify port availability

# Check if ports are already in use
sudo lsof -i :443  # HTTPS API
sudo lsof -i :33073  # gRPC
sudo lsof -i :9090  # Metrics
3

Check database connectivity

# If using PostgreSQL/MySQL
docker compose logs management | grep -i "database\|store"

# Test database connection
docker compose exec management ping postgres
4

Validate configuration

# Check management.json
cat management.json | jq .

# Verify environment variables
docker compose config | grep NETBIRD

​
High Memory Usage (Server)

# Check network map object count
curl http://localhost:9090/metrics | grep network_map_object_count

# Monitor account manager metrics
curl http://localhost:9090/metrics | grep account_manager
Solutions:
  • Optimize peer groups and access rules
  • Consider splitting into multiple accounts
  • Increase container memory limits
# Check lock metrics
curl http://localhost:9090/metrics | grep store_global_lock
Solutions:
  • Switch from SQLite to PostgreSQL for better concurrency
  • Reduce update frequency
  • Scale horizontally with multiple management instances

​
Network Configuration Issues

​
Interface Conflicts

# Check for interface name conflicts
ip addr show

# Use custom interface name
netbird up --interface-name nb0

​
Routing Issues

# Check NetBird routes
netbird networks routes list

# View system routing table
ip route show | grep wt0  # or your interface name

# Check for route conflicts
netbird status --detail

​
Firewall Blocking Peers

1

Check NetBird firewall rules

# Linux iptables
sudo iptables -L -n -v | grep wt0

# nftables
sudo nft list ruleset | grep wt0
2

Verify peer access

# Test connectivity to peer
ping 100.64.0.5

# Test specific port
nc -zv 100.64.0.5 22
3

Check ACL rules

Review access control rules in the NetBird dashboard

​
Getting Help

When seeking help, include:
  1. Debug bundle: netbird debug bundle --anonymize
  2. Client version: netbird version
  3. Operating system and version
  4. Deployment method: self-hosted, cloud, docker
  5. Error messages from logs
  6. Network topology (NAT types, firewalls)
Join the NetBird community:

​
Common Error Messages

ErrorCauseSolution
StatusNeedsLoginNot authenticatedRun netbird up to login
connection timeoutNetwork/firewall issueCheck connectivity to management server
peer not foundPeer offline or removedCheck peer status in dashboard
interface already existsInterface name conflictUse --interface-name flag
permission deniedInsufficient privilegesRun with sudo/administrator
failed to create wireguard deviceWireGuard kernel module missingInstall wireguard-tools

Build docs developers (and LLMs) love

Get started for freeTalk to us