# Troubleshooting

> Fix the most common connection and setup problems, by the message you see.

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](/manage/machines#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](/manage/machines#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](/manage/plans) |
| `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 |

## A device shows `relay`

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](/features/access-controls). 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](https://getunderpass.com/support). Include the output of `underpass status` and the last lines of the log.