Troubleshooting

Work from the bottom layer up: uplink, tailnet control, peer path, rule, application. The Web UI reports each layer separately.

The device does not join the tailnet

Check whether the auth key expired, was revoked or was single-use and already consumed. Use registration credentials appropriate for a persistent gateway and your administrator's policy.
Headscale: check the login server URL and that its certificate comes from a public CA.
Tailnet lock is enabled: it is not supported.

It was working and dropped off after months

Check node-key expiry in the admin console and reauthorize the device if required. Also check the uplink, clock and gateway logs before changing settings. Whether to disable expiry for a persistent recovery node is an administrator policy decision, not a required troubleshooting step.

Tailnet clients cannot reach the LAN

Approve the advertised route in the admin console. If LAN hosts have no route back to 100.64.0.0/10, enable source NAT for advertised routes.

A Service Gateway rule does not work

Run Test destination. Read the reported result: DNS resolution, the tunnel path, the listening service or authorization may be involved. For UDP, use reply evidence from the actual service; there is no TCP handshake to test.
Check that the rule is enabled and not expired, and that the client's address is inside the source CIDR (rejected counter).
Check the client points at the ESP32's address and listen port, not at the remote service.

I cannot reach the Web UI

Use the IP address or the .local name; other host names are refused when no password is set.
If the saved WiFi is gone, wait 60 seconds and join the ESP32's recovery access point.
Too many failed logins pause sign-in briefly; wait instead of retrying repeatedly.

The updater says the GitHub check failed

Check Internet access, the clock used for TLS and the reported GitHub error. For 1.13 or earlier, follow the legacy migration path; a direct upload of the current 3.x application does not fit the old OTA slots.

Still stuck?

Use Devices & Recovery → Sanitized export, review it for private details, and open an issue. Full guide: docs/TROUBLESHOOTING.md.