Troubleshooting

Start with:

bash

underpass status

The first line says whether this machine is connected, and a Problem: line explains what's wrong. The table shows how each other device is reached.

Messages and what to do

Message	Cause	Fix
`the Underpass service isn't running`	The background service is stopped, or you can't reach it	Linux: `sudo systemctl restart tailnetd`. macOS: `sudo underpass service install`. Windows: restart the PC or reinstall. On Linux, log out and back in once after installing, or use `sudo`
`waiting for an admin to approve this machine`	Device approval is on	An admin approves it under Machines
`login link expired before it was approved; start again`	The sign-in link wasn't used in time	Run `underpass up` again
`this machine's key expired; log in again to reconnect`	Key expiry passed	Run `underpass up`
`this machine was removed from the network`	It was removed in the dashboard	Join again with `underpass up`
`auth key is invalid, expired, or already used`	The key is wrong, expired or one-time	Create a new key, or a reusable one
`this workspace's plan allows N machines`	The workspace is at its device limit	Remove a machine or upgrade
`start tunnel (needs root/administrator)`	A standalone run without admin rights	Use `sudo`, or an administrator terminal
`wintun.dll not found next to tailnet.exe`	A broken Windows install	Reinstall with UnderpassSetup.exe
`MagicDNS needs systemd-resolved (resolvectl)`	Linux without systemd-resolved	Install and enable it, or use `100.x` addresses
`forwarding needs nftables`	A Linux subnet router or exit node without nftables	`sudo apt install nftables`
`can't reach coordinator: … (retrying in Ns)`	No internet, or HTTPS is blocked	Check the connection; the app keeps retrying

Some networks block every direct path, and the encrypted relay carries the traffic instead. It still works, just with a little more latency. The devices keep trying for a direct path every 35 to 60 seconds and switch on their own when one works.

Networks that often need the relay: strict corporate firewalls, some guest Wi-Fi, and mobile networks behind carrier-grade NAT.

A name doesn't resolve

Check the device is connected in underpass status.
Try the full name (db-prod.underpass.internal) and the address (100.64.0.21). If the address works, it's DNS:
- Linux: names need systemd-resolved.
- macOS: another VPN may own the resolver file for that domain. The app won't overwrite files it didn't write.
Names are cached for 60 seconds after a rename.

Can't reach a device, but it's online

Check your access rules. Once a policy is saved, anything it doesn't allow is blocked on the receiving device.
Check the app on the device listens on that port, and its own firewall allows it.

A subnet route or exit node isn't used

An admin has to approve it on the Routes page.
underpass status on your device shows Not using other machines' subnet routes if --accept-routes=false.
An exit node is only used while it's online and approved; otherwise traffic goes out directly, and the client logs why.

Logs

System	Where
Linux	`/var/lib/tailnetd/daemon.log`, and `journalctl -u tailnetd`
macOS	`/var/lib/tailnetd/daemon.log` and `/var/log/tailnetd.log`
Windows	`%ProgramData%\TailnetService\daemon.log`

The log starts fresh once it passes 10 MB.

Still stuck

Write to us from getunderpass.com/support. Include the output of underpass status and the last lines of the log.