NetBird client on Windows

Windows-specific steps for the NetBird client. For everything cross-platform (client status, the debug bundle, GRPC and ICE debugging, login failures, and reaching resources), start from Troubleshooting client issues.

Set the log level permanently

The temporary log level resets when the service restarts. To make it permanent, run an elevated PowerShell or cmd.exe window:

[Environment]::SetEnvironmentVariable("NB_LOG_LEVEL", "debug", "Machine")
netbird service restart

Run the client in foreground mode

On Windows the client depends on WireGuard's wintun.dll and can only run as the system account. To run it in foreground mode, use PSExec. In an elevated PowerShell window:

netbird service stop
.\PsExec64.exe -s cmd.exe /c "netbird up -F --log-level debug > c:\windows\temp\netbird.out.log 2>&1"

To pass environment variables, set them as machine-level variables so the client picks them up on the next PSExec run:

[Environment]::SetEnvironmentVariable("PIONS_LOG_DEBUG", "all", "Machine")

SSO login fails to bind TCP 53000

NetBird's interactive SSO login (netbird up, including with --no-browser) needs a local loopback listener to catch the OAuth redirect. The callback port comes from a short list of redirect URLs registered with your identity provider, by default http://localhost:53000/, and often http://localhost:54000/ as well.

So the port is not a single hardcoded value, and self-hosted deployments can set the list with NETBIRD_AUTH_PKCE_REDIRECT_URL_PORTS. What you cannot do is point the client at an arbitrary port, because each one has to be a redirect URI the identity provider already knows. So the fix is to free the port the client needs, usually 53000, not to reconfigure the client.

When the client cannot bind that port, login fails like this:

daemon up failed: sso login failed: ... listen tcp :53000: bind: 

The Winsock error at the end tells you which of the two cases below you are hitting.

Bind forbidden (WSAEACCES / 10013)

The bind fails with "An attempt was made to access a socket in a way forbidden by its access permissions", even from an elevated prompt, and nothing is actually listening on 53000 (netstat shows it free). The port sits inside a Windows reserved dynamic-port exclusion range held by Hyper-V's winnat service (also pulled in by WSL2 and Docker Desktop). This often starts after a Windows Update, or after installing or enabling Hyper-V, WSL2, or Docker, which is why a client that worked for months can suddenly begin failing.

Check whether 53000 falls inside an excluded range:

netsh int ipv4 show excludedportrange protocol=tcp

If it does, reserve 53000 so the dynamic pool stops claiming it, leaving it free for NetBird to bind. In an elevated cmd.exe:

net stop winnat
netsh int ipv4 add excludedportrange protocol=tcp startport=53000 numberofports=1 store=persistent
net start winnat

Reboot, then retry netbird up.

Address already in use (WSAEADDRINUSE / 10048)

The bind fails with "Only one usage of each socket address is normally permitted". Here a process really is holding 53000, often a stale or hung netbird process, or a previous SSO attempt that did not finish.

Find the process holding the port, then identify it by its PID:

netstat -ano | findstr :53000
tasklist /fi "pid eq <PID>"

Close the conflicting process. If it is a stale netbird, restart the service and retry login:

Restart-Service netbird

When neither case fits

Sometimes a port is refused even though netstat shows it free and it is not in any excluded range. This can happen when endpoint security software such as antivirus or endpoint detection and response (EDR), a VPN or packet-filtering driver, or another network shim reserves or intercepts the loopback bind without surfacing it to netstat or netsh. If 53000 looks free by every check above but the bind is still refused, suspect third-party security or networking software: review what is installed and, where policy allows, retest with it briefly paused.

Host-based firewall

Windows Firewall or endpoint security software can block NetBird traffic before it leaves the machine. See Ports & Firewalls: Host-based firewalls for Windows Firewall symptoms, remediation, and diagnostic commands.

Windows DNS scenarios

DNS on Windows has a few platform-specific failure modes worth checking separately:

• Match-domain names don't resolve, even though the NRPT (Name Resolution Policy Table) rule was written. A lingering Group Policy DnsPolicyConfig container can stop NetBird's rule from taking effect on an off-domain machine. See DNS Troubleshooting: Issue 8 (lingering GPO).
• Active Directory login, mapped drives, or DFS fail while a file share by IP works. This is usually a DC-locator (SRV record) problem. See Domain Controllers as routing peers.
• NetBird won't start on a Domain Controller and the peer shows disconnected. The Windows DNS Server service can claim WireGuard's UDP port 51820 before NetBird does, so the tunnel never comes up. See WireGuard port conflict on Domain Controllers.