Troubleshooting

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:

Sets log level to trace
Restarts the connection
Runs for the specified time
Creates a debug bundle
Restores original settings

Connection Issues

Peer Not Connecting

Check daemon status

# Linux/macOS
systemctl status netbird

# Windows (PowerShell)
Get-Service Netbird

# Or use NetBird CLI
netbird status

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"

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

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:

Symptoms

Connections show as “Relayed” instead of “P2P”
High latency between peers
netbird status --detail shows relay connection type

Diagnosis

# 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

Solutions

Verify STUN/TURN servers are accessible:

# Test STUN connectivity
nc -zvu stun.netbird.io 3478

Check symmetric NAT:
- Symmetric NAT prevents direct P2P
- Relay connection is expected behavior

Configure external IP mapping:

# If behind NAT with known public IP
netbird up --external-ip-map 12.34.56.78/10.0.0.1

Open WireGuard port (51820/UDP):

# Linux UFW
sudo ufw allow 51820/udp

# iptables
sudo iptables -A INPUT -p udp --dport 51820 -j ACCEPT

Verify relay server is running:

curl http://relay.netbird.io:8080/health

Authentication Failures

Token Expired

Error: status: StatusSessionExpired or StatusLoginFailedSolution:

# Re-login with SSO
netbird down
netbird up

# Or with setup key
netbird up --setup-key YOUR_SETUP_KEY

Management Server Unreachable

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

IDP Integration Issues

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

Check DNS configuration

# Verify NetBird DNS is configured
netbird status --detail

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

Test DNS resolution

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

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

Check Connection Type

# Verify using P2P when possible
netbird status --detail

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

Network Path Issues

# 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

MTU Problems

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

Check active connections

netbird status --detail
# Count number of connected peers

Profile CPU usage

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

Optimize connection settings

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

# This reduces idle peer connections

Service Issues

Service Won’t Start

Linux (systemd)

# 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

Windows

# 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

macOS

# 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

Locate config file

# Linux
/etc/netbird/config.json

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

# macOS
/etc/netbird/config.json

Validate JSON

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

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

Check container status

docker compose ps
docker compose logs management

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

Check database connectivity

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

# Test database connection
docker compose exec management ping postgres

Validate configuration

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

# Verify environment variables
docker compose config | grep NETBIRD

High Memory Usage (Server)

Large Network Maps

# 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

Store Lock Contention

# 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

Check NetBird firewall rules

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

# nftables
sudo nft list ruleset | grep wt0

Verify peer access

# Test connectivity to peer
ping 100.64.0.5

# Test specific port
nc -zv 100.64.0.5 22

Check ACL rules

Review access control rules in the NetBird dashboard

Getting Help

When seeking help, include:

Debug bundle: netbird debug bundle --anonymize
Client version: netbird version
Operating system and version
Deployment method: self-hosted, cloud, docker
Error messages from logs
Network topology (NAT types, firewalls)

Join the NetBird community:

GitHub Issues: https://github.com/netbirdio/netbird/issues
Slack: https://netbird.io/slack
Documentation: https://docs.netbird.io

Common Error Messages

Error	Cause	Solution
`StatusNeedsLogin`	Not authenticated	Run `netbird up` to login
`connection timeout`	Network/firewall issue	Check connectivity to management server
`peer not found`	Peer offline or removed	Check peer status in dashboard
`interface already exists`	Interface name conflict	Use `--interface-name` flag
`permission denied`	Insufficient privileges	Run with sudo/administrator
`failed to create wireguard device`	WireGuard kernel module missing	Install wireguard-tools

Get Started

Architecture

Deployment

Client Setup

Network Management

Security

Operations

Troubleshooting

Quick Diagnostics

Check Client Status

Generate Debug Bundle

Run Timed Debug Session

Connection Issues

Peer Not Connecting

NAT Traversal Failures

Authentication Failures

DNS Issues

NetBird DNS Not Resolving

DNS Resolution Conflicts

Performance Issues

High Latency

High CPU Usage

Service Issues

Service Won’t Start

Configuration File Issues

Server Issues

Management Server Not Starting

High Memory Usage (Server)

Network Configuration Issues

Interface Conflicts

Routing Issues

Firewall Blocking Peers

Getting Help

Common Error Messages

​Quick Diagnostics

​Check Client Status

​Generate Debug Bundle

​Run Timed Debug Session

​Connection Issues

​Peer Not Connecting

​NAT Traversal Failures

​Authentication Failures

​DNS Issues

​NetBird DNS Not Resolving

​DNS Resolution Conflicts

​Performance Issues

​High Latency

​High CPU Usage

​Service Issues

​Service Won’t Start

​Configuration File Issues

​Server Issues

​Management Server Not Starting

​High Memory Usage (Server)

​Network Configuration Issues

​Interface Conflicts

​Routing Issues

​Firewall Blocking Peers

​Getting Help

​Common Error Messages

Quick Diagnostics

Check Client Status

Generate Debug Bundle

Run Timed Debug Session

Connection Issues

Peer Not Connecting

NAT Traversal Failures

Authentication Failures

DNS Issues

NetBird DNS Not Resolving

DNS Resolution Conflicts

Performance Issues

High Latency

High CPU Usage

Service Issues

Service Won’t Start

Configuration File Issues

Server Issues

Management Server Not Starting

High Memory Usage (Server)

Network Configuration Issues

Interface Conflicts

Routing Issues

Firewall Blocking Peers

Getting Help

Common Error Messages