Troubleshooting

Troubleshooting

Work from the bottom layer up and stop at the first one that fails. Status → Guided setup → Connectivity troubleshooting runs these checks for you.

Layer	Check	If it fails
Uplink	Status: uplink address	Wi-Fi credentials, DHCP/static settings
Gateway / DNS / Internet	Devices & Recovery → layered checks	Router, resolver
Tailscale control	Status: Tailscale connected	Auth key, login server, clock, uplink
Policy authority	Devices & Recovery summary	Wait for a complete control map; data stays closed until then
Peers	Tailscale page: online peers	The peer itself and its ACLs
Service	Service Gateway rule status	See below

Service Gateway rule states

Status	Next step
disabled / ready_to_enable	Enable when the exposure is intended
uplink_no_ipv4, control_not_ready	Fix the lower layer first
destination_unresolved	Use a current 100.x address or MagicDNS name
mapping_not_installed, runtime_error	Read the error; check port conflicts
destination_no_answer	Peer online? Service listening? ACL allows this gateway?
source_rejected	Client address vs the rule's source CIDR or expiry
destination_reachable	Try the allowed LAN client on ESP-IP:listen-port
service_replied	Verify the intended client and application

UDP cannot be tested with a handshake: use the reply evidence.

Common situations

Symptom	What to do
Setup page refuses pairing / "pairing was reset"	Use one browser window, tap Try again, then press BOOT or enter the latest code (it changes at every restart). Use v2.0.1 or later.
Can't find the gateway after setup	Open the address shown at the end of setup or http://esp32-tailnet-xxxx.local/; otherwise look for esp32-tailnet-xxxx in your router's client list
.local name does not open	The client must support mDNS (Windows 10+, macOS, iOS, most Linux/recent Android); on Windows the network profile must allow discovery
untrusted Host without a web password	Open the device by IP address or .local name, or set a web password
Too many failed logins	The device-wide login budget is exhausted; wait the indicated seconds
cross-origin write refused	Open the Web UI directly, not from another site
GitHub update restarts without installing (v2.0.0/v2.0.1)	Update once by hand: Updating
Board not detected for flashing	Data cable, CP210x/CH34x driver, then hold BOOT, tap RESET, release BOOT

Asking for help

Devices & Recovery → Sanitized export produces a local JSON without names, destinations, IPs, ports, credentials or tokens. Attach it to a bug report or start a discussion. Never post passwords, auth keys or backups.

Full guide: TROUBLESHOOTING.md.