Troubleshooting guide

This article contains various suggestions and tips to help troubleshoot common issues. Refer to Troubleshoot device connectivity for connectivity-specific instructions. If you have additional issues, contact support.

• Linux
• Apple
• Windows
• Mobile
• Cloud
• Network
• Containers
• General

Linux

Linux DNS issues

For details, refer to DNS issues see Configuring Linux DNS.

Apple

Access macOS files from an iPhone

1. Open the Files app on your iPhone.
2. Go to the Browse tab.
3. Select the in the top right.
4. Select Connect to Server and enter your Mac's Tailscale IP address.

Any folders shared by your Mac (using SMB) can now be browsed.

Apple TV access issues

Refer to Install Tailscale on an Apple TV for troubleshooting guidance.

macOS gets stuck at Loading backend...

Do you have Screen Time enabled? Refer to macOS Screen Time and Tailscale for troubleshooting guidance.

Do you have a virus scanner (or other form of endpoint security) such as ESET installed? In some cases we've found that security measures interfere with Tailscale's operation.

macOS ping issues

macOS' "stealth mode" will prevent macOS from responding to pings. This can be enabled or disabled in your Mac's Security & Privacy settings. Refer to this issue for updates on improving related notifications and user experience.

macOS system extension errors

Refer to Authorizing the Tailscale system extension on macOS for troubleshooting guidance.

Windows

Windows ping issues

Windows generally has aggressive firewall rules set up, even for ICMP (ping) traffic (both incoming and outgoing). Be sure that you've enabled your Windows devices to be able to both send and receive ICMP traffic.

A faster, but riskier approach to test this is to (temporarily) disable the Windows firewalls to see if it makes any impact. Refer to this issue for updates on improving related notifications and user experience.

Windows Remote Desktop (RDP) login issues

If you log in to Windows locally using a PIN (Windows Hello) you might find you're unable to log in over Remote Desktop (RDP). Windows requires traditional account passwords for RDP connections.

If you do not have an account password, for example, Windows 11 defaults to using a PIN (Windows Hello), you will want to change your sign-in options and enable password authentication. You can find more information from the Microsoft Support article Windows sign-in options and account protection.

Windows update connectivity issues

As part of some Windows 10 and Windows 11 updates, the SYSTEM user’s %LocalAppData%, usually at C:\WINDOWS\system32\config\systemprofile\AppData\Local, is wiped. This directory is where Tailscale 1.14.3 and earlier stored its internal state.

If you upgraded your Windows device and lost connectivity to Tailscale, you can either:

1. (Recommended) Remove the old device using the admin console, and then re-login to Tailscale from the affected Windows device. This needs both a Tailscale admin and someone with access to the device to take action.
   • Open the Machines page of the admin console. Find the row corresponding to the device that is affected. Select the menu at the far right and select the Remove option. This will remove the device from your tailnet.
   • Upgrade the affected Windows device to Tailscale v1.14.4 or later.
   • The affected Windows device should now prompt you to log in again to rejoin your tailnet. If device approval is enabled, the device will need to be re-approved.
   • With this option, the device will retain the same name, but have a new IP address.
2. Remove the remaining Tailscale state files from the Windows device, and then re-login to Tailscale. This does not require an admin to take action, unless device approval is enabled.
   • For the affected device, remove all files in the %LocalAppData%\Tailscale directory. To do this, you can open cmd.exe and run
     rmdir /s %LocalAppData%\Tailscale\
   • Upgrade the affected Windows device to Tailscale v1.14.4 or later.
   • Re-login to Tailscale on the device. If device approval is enabled, the device will need to be re-approved by an administrator.
   • With this option, the device will be assigned a new name (for example, old-name-1), and have a new IP address. The device’s old name will still be listed in the admin console until it is removed. At that time, the admin can rename the new device to the old name.

To avoid this issue in the future, upgrade Windows device to v1.14.4 or later prior to performing a Windows update.

Windows version support

Mobile

Mobile device battery drains too quickly

This is a known issue. However, we are continuously making improvements. Battery drain is most commonly attributed to a device using an exit node for all traffic.

Disable specific apps from using Tailscale

On Android devices, you can use app-based split tunneling to choose which apps will bypass or be forced to use the tailnet.

Cloud

AWS cannot access Google after setting up --advertise-routes=172.0.0.0/8

Only part of the 172.0.0.0/8 range is private. The rest is public address space and Google has IP addresses in that range for some of its data centers.

You can safely advertise the 172.16.0.0/12 range instead:

tailscale up --advertise-routes=172.16.0.0/12

Cloud Linux VM issues

See the topic Access Oracle Cloud VMs privately using Tailscale for troubleshooting guidance.

Subnet router connectivity issues in a cloud environment

The most common issue in AWS, Azure Cloud, and GCP that we've seen is a security group being too restrictive, and blocking connections. For troubleshooting purposes, try setting the internal security group to allow all traffic on the subnet, and the security group on the subnet router itself to allow all traffic to see if that unblocks connections.

Network

Which firewall ports need to be opened

For details, refer to the topic What firewall ports should I open to use Tailscale?.

CGNAT conflicts

Tailscale assigns each device in your tailnet a unique 100.x.y.z address. This is called the carrier grade NAT (CGNAT) address space, reserved by RFC6598, IANA-Reserved IPv4 Prefix for Shared Address Space. CGNAT conflicts can arise, for example, if your internet service provider (ISP) also uses the 100.64.0.0/10 subnet (from 100.64.0.0 to 100.127.255.255).

If you are experiencing CGNAT conflicts, you can disable IPv4 in your tailnet. This will cause Tailscale to use IPv6 only. To do this, add the following to your tailnet's ACLs in the admin console.

{
    "DisableIPv4": true
}

Be aware that disabling IPv4 will prevent you from accessing IPv4-only resources on your network. For example, IPv4-only exit nodes will not be accessible.

Deploy Tailscale to a fleet of devices

You'll want to use Tailscale's pre-authenticated keys feature, which let you authenticate devices by key rather than in-browser.

As an Admin, you can create keys in the admin console once you're logged in.

DERP traffic route checking

More in depth information is provided to troubleshoot direct and relayed connections. Use the Tailscale CLI to run the tailscale status command. If you see output in the form of relay "code", then your traffic is being routed through a relay server that has "code" as its location. For example, the second line in this tailscale status output indicates traffic is being routed through the "sea" (Seattle) relay server:

100.99.98.97 device1 linux active; direct 1.2.3.4:1234; tx 1000 rx 1000
100.99.98.96 device2 linux active; relay "sea", tx 1000 rx 1000

If there is no relay "code" line in the tailscale status output, then your traffic is not being routed through DERP.

Also, the tailscale ping command will indicate whether a successful ping was by direct path or using DERP. tailscale ping will keep trying until it either sends 10 pings (the default if not using the --c flag) through the relays, or finds a direct path. For example, if the first five pings were relayed and the sixth ping was a direct path, tailscale ping will stop. This tailscale ping device2 example indicates the device was reached using the "sea" relay on the first ping, and via direct path on the second ping, at which time tailscale ping stopped.

tailscale ping device2

pong from device2 (100.99.98.96) via DERP(sea) in 242ms
pong from device2 (100.99.98.96) via 1.2.3.4:1234 in 127ms

Disable subnet route masquerading

You can disable subnet route masquerading with the following command:

tailscale up --snat-subnet-routes=false

DNS errors for internal service connectivity

If you are using DNS names to access internal services and some people have difficulty connecting to those services, the problem might be caused by DNS Rebinding Protection.

IP forwarding errors when using advertise-routes

Tailscale's routing features (subnet routers and exit nodes) require IP forwarding to be enabled. If it is not enabled, you may see an error when using --advertise-routes or --advertise-exit-node.

To learn how to do this for your Linux device, refer to how to enable IP forwarding.

IP routes that Tailscale installs

As of v0.99, Tailscale routes moved into a separate routing table (to prevent routing loops in subnet routers), which the legacy netstat tool doesn't display.

To see routes installed by Tailscale use ip route instead, use the following command:

ip route show table 52

LAN traffic prioritization with overlapping subnet routes

You may have a LAN subnet that contains a mix of both Tailscale devices, and non-Tailscale devices that all must accept routes in order to communicate with a second subnet. In this condition routing can become asymmetric leading to new configuration challenges. To work around this challenge, there are different solutions depending on the operating system of the affected device.

On both Windows and macOS, routes are accepted by default. The operating system will prioritize routes with the longest prefix match, or in other words the most specific of all configured routes. A solution for overlapping subnet routers is therefore to adjust the Tailscale advertised route to be less specific than the LAN subnets that you wish to avoid routing conflicts with. If for example, you have a LAN subnet of 192.168.2.0/24 and you wish to avoid routing traffic to that subnet through Tailscale when devices are on this LAN segment, you can configure the subnet router to advertise a route of 192.168.2.0/23.

On Linux, the --accept-routes flag must be passed explicitly to tailscale up in order to accept subnet routes from other devices in the tailnet. Tailscale on Linux uses a routing feature known as policy routing that introduces an additional layer of prioritization to routing.

Tailscale uses IP rules in the priority range of 5200 to 5500 to prioritize routes, at this time 5210, 5230, 5250 and 5270.

Install a rule ahead of the Tailscale rules that uses lookup to jump over them:

ip rule add to 192.168.2.0/24 priority 2500 lookup main

The above command installs a rule that matches traffic destined for 192.168.2.0/24 in a rule with priority 2500 (a higher priority than the Tailscale rules). When matched, the rule jumps to the main routing table, which is the default routing table. This rule will therefore take precedence over the Tailscale rules, and use the regular LAN routes in the main routing table.

Multiple devices have the same 100.x IP address

This can occur if you use a backup of one device to create another, or clone a file system from one device to another. The Tailscale configuration files are duplicated. The Tailscale files will need to be removed from one of the two.

You can identify duplicated devices in the Machines page of the admin console by looking for a Duplicate node key badge underneath the device name.

On one of the systems, uninstall and completely delete the Tailscale app. It is especially important to remove the files listed for your platform, the goal is to make a new Tailscale IP address when it is installed again. Then, reinstall the app.

Network traffic examination inside an encrypted tunnel

It is sometimes useful to be able to see the unencrypted packets inside the WireGuard tunnel using tools like Wireshark. This can only be done from one of the devices at the endpoints of the tunnel, packets captured in flight from the network can not be decrypted.

From the devices at the endpoints of the tunnel there are several ways to accomplish this:

1. tailscale debug capture -o /path/to/capture.pcap
2. Run Wireshark on the tun device (does not work in userspace-networking mode).

With tailscale debug capture the -o /path/to/capture.pcap argument specifies the name of a file to write packets to. If omitted, Tailscale will attempt to start Wireshark locally for a live capture. These pcap files are captured with a header of metadata about the tailnet. To view them in Wireshark one must install a Lua dissector.

To capture from a tun device one starts Wireshark and has it capture from:

1. tailscale0 for Linux and Windows systems.
2. utun# on macOS, where the number can vary. Wireshark will show a list of interfaces, and one of the utun interfaces should show some traffic.

Wireshark 3.65 or later support capturing Wireshark frames from TUN devices.

Route all traffic through a default route

On Tailscale, you can define an exit node, which automatically configures default routes on your behalf.

If you want to force your traffic through a particular IP (to handle an IP blocklist or IP allowlist) you can also route only a subset of your traffic using subnets. Refer to Connecting to external services with IP blocklists via Tailscale for more details.

SoraCOM issues

Tailscale can work on SoraCOM but not with the ISP's DNS servers. We recommend enabling the Override local DNS toggle on the DNS page of the admin console.

Sunrise Communications issues

It appears that Sunrise Communications is blocking the Tailscale service.

Specifically, Tailscale has been (incorrectly) flagged by Sunrise's Surf Protect as a potentially malicious application.

To use Tailscale, you'll need to work with Sunrise support:

• Find your Sunrise site ID.
• Contact Sunrise support at Sunrise support, and ask that *.tailscale.com and *.tailscale.io be added to the exclusion list for your Surf Protect subscription. Alternately if desired, you could remove Surf Protect from your account.

Tally ERP issues

Tally appears to bind to interfaces in a way which conflicts with VPN software like Tailscale. If the license server is running on the local device, changing the Tally configuration via the UI or by editing Tally.ini to use 127.0.0.1:9999 as the license server instead of using the PC hostname allows it to work.

TCP connection issues between two devices

If your devices are visible in the admin console, and there is no access rule blocking connections between the devices, check the level of connectivity with Tailscale's three types of ping:

• ping 100.x.x.x tells the OS to send an ICMP ping across the tailnet.
• tailscale ping 100.x.x.x tests whether the two tailscaled processes can communicate at all, and how (direct, or relayed).
• tailscale ping --tsmp 100.x.x.x sends a packet that goes one level further than tailscale ping, also going through the WireGuard level, but doesn't involve the host's networking stack.

Packet size limits can also cause connection problems on certain types of networks.

Tailscale uses a maximum transmission unit (MTU) of 1280. If there are other interfaces which might send a packet larger than this, those packets might get dropped silently. These can be verified by using tcpdump.

To solve this, we can set the MTU at the LAN level to a lower value, or use MSS (maximum segment size) clamping.

Containers

Kubernetes issues

Refer to Troubleshooting the Kubernetes operator for troubleshooting guidance.

Proxmox issues

Refer to Tailscale on a Proxmox host for troubleshooting guidance.

General

Antivirus flagging

The Tailscale client can be falsely flagged by antivirus software, especially with new releases, because many antivirus engines use machine learning and other automated tools that can result in false positives. See the topic Antivirus flagging of the Tailscale client to learn what to do when Tailscale is being flagged by antivirus software and how to report legitimate concerns.

Captive portal notifications

When you connect to a public network, you might be redirected to a captive portal requiring you to authenticate or accept terms before accessing the internet. Refer to Using Tailscale with captive portals for troubleshooting guidance.

Client bug reports

You can generate a bug report from within the Tailscale client, and you can send this report to us to help you troubleshoot issues more effectively.

Device connectivity issues

Refer to Troubleshooting device connectivity for troubleshooting guidance.

Interoperability with other software

Tailscale tries to cooperate and run alongside other software on your device, but sometimes that's not possible. Some operating systems impose limitations on how many VPN-type programs can run at once or register with certain OS-level facilities, and sometimes other software accidentally or by design breaks Tailscale.

When debugging issues where Tailscale doesn't work, we generally start by trying to identify how your device or network is different and what other software you're running on the device that's apparently conflicting. Here are some general questions to consider:

• Are you running any other networking, VPN, endpoint security, antivirus, virtualization or other security software?
• Any security proxy on the network/router?

A non-exhaustive list of other software that may or may not cause problems, depending on OS/versions/configs:

• Apple Private Relay
• Apple Screen Time (or any other macOS content filters)
• Avast
• Clash, ClashX, Clash Pro X
• Cloudflare Warp
• CrowdStrike Falcon
• Docker Desktop
• FortiClient
• GlobalProtect VPN
• Little Snitch
• McAfee LiveSafe
• Mullvad
• Netskope
• PIA
• TunnelBear
• Tunnelblick
• VMWare Carbon Black
• Webroot
• WireGuard
• VirtualBox
• VMWare
• WSL
• ZeroTier

Let us know if you're running one of those, or similar programs. On some operating systems Tailscale is not even able to detect the presence of those programs due to sandboxing. If you let us know what you're running, we might be able to advise you on how to configure things to work.