Troubleshoot by layer

“Tailscale is down” is not a diagnosis. The failure can live at any of several independent layers, and each one has its own test.

Here is the order I use. Identity first: is the device logged in? Device state: are both peers connected? Name resolution: does the MagicDNS name resolve? Policy: does a grant allow this source to reach this destination and port? Route: is a subnet route or exit node involved? Then the destination port, and finally the application itself.

Work top to bottom. A failure at one layer makes every layer below it fail too, so starting at the bottom wastes time.

The three commands

Three commands cover most of the layers:

tailscale status
tailscale ping lab-server
tailscale netcheck

tailscale status shows peers and their state. If the destination is missing or shows offline, stop there. tailscale ping explains the path, direct or relayed, and fails fast if policy blocks you. tailscale netcheck reports what your local network allows, like outbound UDP.

Separate the tests

Test names, reachability, and the Tailscale path separately:

tailscale status
tailscale ping server-name
ping -c 3 server-name
tailscale netcheck

tailscale ping tells you whether the peers can establish a Tailscale path and whether it is direct or relayed. Ordinary ping also depends on the destination operating system and firewall. If the name fails, retry with the Tailscale IP before changing ACLs or routes.

Read the difference

The two pings answer different questions. tailscale ping working while ping -c 3 fails means the tailnet path is fine and the destination’s firewall is dropping ICMP. Both failing by name while tailscale ping 100.101.9.23 works means DNS. tailscale ping failing outright with a peer that shows online points at policy.

In my experience, “Tailscale is down” is nearly always one of three things: a typo in a grant, MagicDNS disabled on one client, or a host firewall that never learned about tailscale0.

Break it on purpose

Break one layer at a time on your lab setup: disable MagicDNS, remove a grant, stop the listener, or drop a route. For each break, record which command identifies the failure, without changing unrelated settings.

That list becomes your runbook. When something breaks for real, you will know which command to run first, and you will know what a healthy answer looks like because you wrote it down while everything worked.