Troubleshooting client issues
This page helps you find out why a device does not connect or cannot reach what it should. Work from the symptom: each section lists what to check, the cause and the fix. Error messages are quoted as the client prints them.
Most problems come from configuration, the network or the sign-in, not from a broken install. Do not reinstall the client as a first step: on Windows an uninstall deletes the device's identity, and the device comes back as a new peer.
Stopping the client logs the device out. netzilo down, netzilo service stop
and netzilo service restart reset the device's keys. A setup-key device then needs
netzilo up --setup-key <KEY> again; an SSO device needs the person at the device to
sign in. Use netzilo refresh to re-sync without logging out, and plan the sign-in
before you restart a remote device.
Start here
Run these three commands on the affected device:
netzilo version
netzilo status -d
tail -n 200 /var/log/netzilo/client.log # Windows: %ProgramData%\Netzilo\client.log
netzilo status -d answers most questions. The summary at the end looks like this:
Management: Connected
Signal: Connected
Relays: 2/2 Available
Nameservers: 1/1 Available
FQDN: laptop-01.netzilo.network
Netzilo IP: 100.64.12.7/16
Peers count: 2/3 Connected
Each peer block shows Status, Connection type (P2P or Relayed), the ICE
candidate types, the last WireGuard handshake, the transfer counters and the latency. See
CLI for every field.
Before you go deeper, rule out four things that look like client faults:
- Another VPN holds the default route or a route to the same destination. Disconnect it and test again.
- The clock is wrong. Certificate checks and the sign-in fail, and the errors point at TLS. Turn on automatic time.
- A captive portal (hotel, airport, guest Wi-Fi) is not completed. Open a browser, complete it, then reconnect.
- A proxy or firewall that inspects TLS sits in the path. Exempt the Netzilo management, signal and relay hosts.
The CLI cannot reach the client service
failed to connect to daemon error: … If the daemon is not running please run: netzilo service install / netzilo service start
| Check | Command |
|---|---|
| Service state | Linux systemctl status Netzilo; macOS sudo launchctl print system/Netzilo; Windows sc query Netzilo |
| Socket | Linux and macOS ls -l /var/run/netzilo.sock; Windows netstat -ano | findstr 40836 |
Start the service with sudo netzilo service start. If it is missing, run
sudo netzilo service install && sudo netzilo service start.
failed to listen daemon interfacein the log: a stale socket or a busy port. Remove/var/run/netzilo.sock(or free port 40836) and start the service.- A Windows non-admin install has no service. Its per-user client listens on its own port, and the CLI of the same user finds it without flags.
- On macOS, if
netzilois not found, open a new terminal or use/Applications/Netzilo.app/Contents/MacOS/netzilo.
The device cannot sign in
netzilo status shows Daemon status: NeedsLogin or LoginFailed.
A failed netzilo up prints login failed: <reason> straight away when retrying cannot
help, and login backoff cycle failed: <reason> after about 30 seconds of retries for
everything else.
| Message | Cause | Fix |
|---|---|---|
NeedsLogin after it worked before | the login expired (24 hours by default for SSO devices), or the client was logged out by down, a service stop or restart | run netzilo up at the device. Enrol servers with a setup key, which does not expire |
LoginFailed | management not reachable, a TLS failure, a wrong URL, an invalid setup key or token | read the failed login: line in the client log. curl -sS -o /dev/null -w "%{http_code}\n" https://<management-host>/api/users must return 401 |
failed adding new peer: account not found | the setup key is unknown to this server: mistyped, deleted, or from another server | copy a key from Endpoint > Setup Keys of the right server, and check the management URL |
couldn't add peer: setup key is invalid | the key is expired, revoked or used up | create a new key, or raise its usage limit |
invalid setup-key format | the key is mistyped | copy it exactly |
peer is not registered during a session | the peer was deleted in the dashboard | enrol again with a setup key or SSO |
invalid PAT token, PAT token expired | the access token is wrong or expired | create a new token, delete pat.dat and unset NETZILOPAT |
no SSO provider returned from management. Please proceed with setting up this device using setup keys | the self-hosted server has no device sign-in configured | use --setup-key, or fix the server's identity provider settings |
no available port found from configured redirect URLs | local ports 53000 and 54000 are busy during the browser sign-in | free the ports; on a machine without a desktop the CLI uses a code instead |
authentication timeout after N seconds, waiting for browser login failed | the browser sign-in was not finished | run netzilo up again and finish it |
user is blocked | an administrator blocked the user | unblock the user under Team > Users |
maximum number of personal peers reached | the plan's peer limit is reached | remove peers or upgrade the plan |
user does not belong to any of the allowed JWT groups | the account allows only certain identity-provider groups | fix the user's group membership or the setting under Settings > Groups |
On a server without a browser, netzilo up prints a URL and a code. Open the URL on any
device. A setup key is simpler for servers.
Connected, but peers are unreachable
Read netzilo status -d for the peer you cannot reach.
| What you see | Meaning | Fix |
|---|---|---|
Status: Disconnected, Last WireGuard handshake: - | no path was found, or the other peer did not answer (offline, signed out) | check that both sides show Relays: n/n Available and allow outbound UDP |
Connection type: Relayed | direct UDP is blocked; traffic uses a relay, with higher latency | allow outbound UDP to any port. Behind 1:1 NAT, set netzilo up --external-ip-map <public-ip> |
Connected, but the handshake is older than about three minutes | the tunnel is stale | check that both peers use the same --preshared-key, or neither. Raise the log level to debug and read the connection lines |
| The peer is not listed at all | no enabled policy connects the two peers' groups | check Network > Policies. Only allow rules exist; one-way TCP and UDP rules need ports |
ping works, the service port is refused | the policy allows the protocol but not the port, or the target's own firewall blocks it | check the policy's ports and the target's firewall |
| All peers dropped after a Wi-Fi or dock change | the client restarted its connections after the network changed | wait 10 to 20 seconds. netzilo refresh re-syncs but does not rebuild tunnels |
peer.access.blocked events under Activity > Events | a posture check failed | the event names the check and the reason. Fix the device or the check |
Two peers talk only when an enabled policy covers a group of each, and every posture check on that policy passes for the source peer.
Management, signal or relays are not reachable
| Status line | Fix |
|---|---|
Management: Disconnected, reason: … | allow outbound TCP 443 to the management host. Behind a corporate proxy, use netzilo up --proxy http://proxy:3128 or --proxy auto. If the proxy strips HTTP/2, set NB_FORCE_WS=1 in the service environment |
Signal: Disconnected | as above |
Relays: 0/2 Available | allow outbound UDP and TCP 3478 and 5349 to the relay host. netzilo status -d lists the relay addresses |
Nameservers: 0/1 Available | the DNS server sent to this peer is not reachable through the tunnel. Check the route and policy to it (UDP 53) |
The client keeps retrying management and signal on its own, so once the path is open no restart is needed.
Network interface problems
| Log message | Platform | Fix |
|---|---|---|
failed creating tunnel interface, interface wt0 don't have an ipv4 address | Linux | modprobe tun; in a container add --cap-add=NET_ADMIN and /dev/net/tun; if another interface is named wt0, use --interface-name |
couldn't access device /dev/net/tun … add flag --cap-add=NET_ADMIN | container | add the capability and the device |
Interface type: Userspace on Linux | Linux | the WireGuard kernel module is missing. It works; install the module for speed |
invalid interface name … Please use the prefix utun followed by a number on MacOS | macOS | --interface-name utun100 |
| no network adapter, wintun errors | Windows | wintun.dll must sit next to netzilo.exe in %ProgramData%\Netzilo Client. Check whether antivirus quarantined it, then reinstall |
no firewall manager found, trying to use userspace packet filtering firewall | Linux | install nftables or iptables. Policies are still enforced meanwhile |
Connected but nothing routes? A client that does not run as root (Linux, macOS) or as
SYSTEM (Windows) is forced into userspace mode without saying so: there is no network
interface, and only the local SOCKS5 proxy reaches peers. This includes a Windows
non-admin install and netzilo up -F from an elevated, non-SYSTEM shell. netzilo status does not show it. Check that the client runs as root or SYSTEM and that the host
has the Netzilo interface.
DNS
| Symptom | Fix |
|---|---|
<peer>.netzilo.network does not resolve | check the Nameservers line. Linux: resolvectl status, nmcli device show wt0 or /etc/resolv.conf; macOS scutil --dns | grep -A3 Netzilo; Windows Get-DnsClientNrptRule shows Netzilo-Match |
the DNS manager of this peer doesn't support custom port. Disabling primary DNS setup. | port 53 is taken. Stop the program that uses it, or set --dns-resolver-address 127.0.0.1:5053 |
| DNS servers with match domains are ignored on Linux | the host does not use systemd-resolved or NetworkManager. Add a DNS server without match domains for the group, or move the host to systemd-resolved |
broken params in resolv.conf, repairing it... | another tool rewrote the file; the client repairs it |
| Windows: DNS broken after uninstall | the Netzilo-Match rule was left behind. Remove it with Remove-DnsClientNrptRule |
In userspace mode the host resolver is not changed. Netzilo names resolve only through
the proxy, with socks5h://127.0.0.1:<port>.
Routes and exit nodes
| Symptom | Fix |
|---|---|
| The route does not show on the device | netzilo routes list. The peer must be in a distribution group of the route and the route must be enabled. Run netzilo refresh |
| The route is there, but traffic fails | a policy must allow the traffic from the device's group to the routing peer's group. Masquerade must be on unless the network routes back to 100.64.0.0/10 |
| Two routes cover the same network | netzilo routes select <id> picks one; select all restores the default |
| No internet through an exit node | IPv6 is not routed through exit nodes. Add a DNS server without match domains for the same distribution group, and check the exit node's own internet access |
doesn't support default routes … skipping this prefix | the client is too old for exit nodes, or runs with NB_DISABLE_CUSTOM_ROUTING=true. Upgrade, or remove the variable |
| Exit node on a Linux client fails with a sysctl error | set NB_USE_LEGACY_ROUTING=true in the service environment |
SSH
| Message | Fix |
|---|---|
you must have Administrator privileges to run this command | run with sudo or from an elevated terminal |
Couldn't connect. Please check the connection status or if the ssh server is enabled on the other peer | the target needs netzilo up --allow-server-ssh and SSH Access turned on for the peer in the dashboard |
the target log says running SSH server is not permitted | --allow-server-ssh is off on the target |
| sign-in fails | the OS user must exist on the target; the default is root |
TLS errors in AI tools and other apps
The client runs a TLS-inspecting proxy on 127.0.0.1:41339 and trusts its own
certificate authority, Netzilo Edge CA, in the operating system. On Windows and macOS,
traffic is sent through it only for the apps named in an endpoint filter's Agents
list.
| Symptom | Fix |
|---|---|
| An app shows a certificate error for an AI or SaaS site | the app does not use the OS trust store. Python, curl: export SSL_CERT_FILE=/etc/netzilo/netzilo-ca.pem REQUESTS_CA_BUNDLE=/etc/netzilo/netzilo-ca.pem. Java: import the CA into cacerts. Firefox: turn on enterprise roots. An app that pins certificates must be removed from the filter's Agents |
MITM: CA trust install failed (manual trust may be required) | trust the CA by hand. macOS: sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /etc/netzilo/netzilo-ca.pem. Debian: copy it to /usr/local/share/ca-certificates/netzilo-mitm-ca.crt and run update-ca-certificates |
MITM: certutil -addstore failed (Windows) | from an elevated prompt, run certutil -addstore -f Root "%ProgramData%\Netzilo\netzilo-ca.pem", and check that security software did not block it |
| Claude Code, Codex or other Node tools fail TLS on Windows while browsers work | the tools run in a desktop session that started before the install. Sign out of Windows and back in |
MITM: existing CA files invalid (…) — regenerating | the client made a new CA. Redo every manual trust step with the new netzilo-ca.pem |
MacFilter: manager exited with error | approve the system extension in System Settings > General > Login Items & Extensions |
unified proxy stopped with error | port 41339 is in use. Use netzilo up --socks5-port <port> |
An agent gets 401, 403, 405 or 429 from the AI Gateway | this is not a client problem: the gateway refused the request. See AI Gateway |
macOS needs three approvals: a network extension, a security extension and Full Disk Access. With only the first, the tunnel works but the AI security features do nothing.
Upgrade and install problems
| Symptom | Fix |
|---|---|
| After the Linux install script the peer appears twice or asks to sign in | the script logs the peer out. Delete the stale peer and enrol again |
Admin mode is already installed, please uninstall Netzilo Client and try again. | a non-admin install over an admin install. Install elevated, or uninstall first |
netzilo is not recognised in a terminal | open a new terminal, or use the full path |
| The dashboard says Update available but the tray shows no update | download the new version from the Add Peer dialog |
| The tray shows different GUI and Service versions | the two come from different installs. Reinstall |
More installer messages are in Installer command lines.
Turn on detailed logs
Raise the level at runtime. No restart, and it returns to normal when the service restarts:
netzilo debug log level debug # or trace
At debug, the log shows connection setup (ICE) lines tagged [pion: …]. Reproduce the
problem, collect a bundle with sudo netzilo debug bundle, then set the level back to
info.
A permanent level means changing the service, which logs the device out:
sudo netzilo service uninstall && sudo netzilo service install --log-level debug && sudo netzilo service start
Do this only when someone can sign the device in again. Avoid netzilo debug for: it
logs the device out twice.
Where the logs are. Linux and macOS: /var/log/netzilo/client.log. Windows:
%ProgramData%\Netzilo\client.log. Logs rotate at 5 MB. On macOS, crash output goes to
/var/log/Netzilo.err.log, which the bundle does not include. The tray's Support >
Open Logs Folder opens the folder.
Related Documentation
- Report bugs and issues - what to send to support and how to redact it
- CLI - every command, flag and file
- Install Netzilo - install, enrol and upgrade on every platform
- Policies - why two peers can or cannot talk
- Routes - routing peers and distribution groups
- DNS - DNS servers and match domains