Troubleshoot device connectivity

Connectivity problems can range from latency and packet loss to an inability to connect to another device or the internet. Depending on the symptoms, the problem could originate from firewall rules, authentication problems, access control rules, routing issues, network instability, and misconfigurations. This troubleshooting guide covers some of the more common connectivity issues in a Tailscale network (known as a tailnet). These include:

Failure to connect
Poor network performance
Failure to resolve domain names

Failure to connect

This section provides troubleshooting guidance for failure to connect to the internet, another tailnet device, or another device in the local network (LAN).

Failure to connect to the internet

Use the following steps to help you troubleshoot why a device can’t connect to the public internet.

Before checking anything else, ensure neither device is experiencing any fundamental network connectivity problems.

Make sure the device has internet access.

You can do this by trying to open a website such as https://tailscale.com in a browser or using a terminal application to ping a well-known IP address, such as one of Google’s DNS servers (8.8.8.8).

If you can ping an IP address but can’t open a URL in a browser, the device is likely unable to resolve domain names.
Check for a captive portal.

Tailscale has the ability to detect captive portals. However, if you haven't received a captive portal alert and you still suspect the device might encounter a captive portal, open http://neverssl.com in a browser. This should reveal a captive portal if one exists.

If you encounter a captive portal (and you trust the network): Disconnect from Tailscale, login to the captive portal, then reconnect to Tailscale.
Ensure you aren’t using a service that uses the same CGNAT IP address range as Tailscale.

Because Tailscale uses the CGNAT IP address range for Tailscale IP addresses, you might encounter problems accessing other non-Tailscale IP addresses in this range.

You can resolve an issue like this, you can update your tailnet policy file to disable IPv4 or use a custom IP pool.
Check for other Tailscale configurations that might prevent a connection.

For example, if the device uses an exit node, make sure the exit node is online and has access to the resources you’re trying to access. For example, ensure no access control policies prevent the exit node from reaching the destination.
Disconnect from any other virtual private network (VPN) software.

While Tailscale doesn’t deliberately conflict with other VPNs, it’s difficult to avoid conflicts in all environments. Many VPN programs also try to prevent other software, such as Tailscale, from making network configuration changes.
Disconnect from Tailscale.

If the problem persists, continue troubleshooting basic network connectivity (beyond Tailscale).

Failure to connect to other tailnet devices

Use the following steps to help you troubleshoot why a device can’t connect to another device in the same tailnet.

Ensure the Tailscale client is up-to-date.

Make sure both devices are running the latest version of Tailscale. You can check the version of every device in your tailnet from the Machines page of the admin console.

You can also check the version of each device locally using the Tailscale application or the tailscale version command. This command also has flags available to check the version of the Tailscale client or the tailscaled daemon specifically.

If the Tailscale version is outdated, download and install the latest version.
Check the status of the Tailscale client.

Check the Tailscale client status of each device using the tailscale status command. This command lists the status of the current device's connection to every other device in the tailnet to which it has access. If a device isn’t listed, check your tailnet policy file for access control policies that might prevent a connection.
Verify Tailscale connectivity.

Use the tailscale ping command to verify each device’s connection to other tailnet devices. This command also has additional flags, such as --verbose, which you can use to get more information.
Check each device's firewall settings.

Check each device’s local and network firewall settings to ensure no firewall rules prevent a connection between the two devices or to Tailscale.
Check Tailscale access control policies.

It’s possible that you can't access an endpoint despite the absence of connection problems. This could be due to your tailnet’s access control policies.

Owners, Admins, and Network admins can check these policies from the Access Controls page of the admin console. Pay special attention to the ACLs, grants, and SSH sections of the tailnet policy file.

Ensure the device can access the IP address or subnet of the other device and the port number of the service you’re trying to access. For example, if the service you’re connecting to is on port 53, ensure no access control policies prevent you from using port 53.

You can use the Preview Rules view to better understand what your access control policies allow.

You can also check Tailscale’s logs on the receiving device. Each time a device attempts a connection, the receiving device logs whether it allowed or denied the connection.
Confirm each device’s authentication status.

Confirm that each device is authenticated with the correct credentials (whether a user account or a tag-based identity). It’s also possible that a device’s authentication has expired.
Check exit node and subnet router configurations.

If either device uses an exit node, ensure the exit node (or subnet router) is online and configured correctly. For example, ensure no access control policies prevent the exit node from accessing the other device.

If either device is behind a subnet router, ensure the other device can access the routes the subnet router is advertising. For example, if the subnet router advertises 192.0.2.0/24, the other device must have access to 192.0.2.0/24.

Failure to connect to the local area network (LAN)

Use the following instructions to help you determine why you can’t establish connection to another device on your local area network (LAN).

Ensure there aren’t any traditional problems interfering with a local connection.

There are many reasons why devices on the same local area network might be unable to connect. For example, firewall rules, IP address conflicts, network misconfiguration, and DHCP errors can prevent connections between LAN devices.

To test the local connection in isolation, disconnect from Tailscale, then try to connect to the LAN device again.
Check if you can connect using the device’s Tailscale IP address (instead of its private IP address).

If the device runs Tailscale and you have a subnet router that advertises your LAN, then your device and other LAN devices have two ways to reach each other. Tailscale typically configures the routing table to prefer the subnet router (if accepting subnet routes is enabled).

The Tailscale client drops packets with unexpected source IP addresses (in this example, the device’s LAN IP address instead of the device’s Tailscale IP address). If the subnet router runs Linux and has SNAT disabled (it can not be disabled on other operating systems), this can lead to a situation where your device’s connection attempts successfully reach the LAN device, but it will be unable to respond.

If you do not need a device to use subnet routes, you can disable them by passing --accept-routes=false to the tailscale up or tailscale set commands or by disabling the subnets option in the Tailscale client (if applicable).

For more information, refer to LAN traffic prioritization with overlapping subnet routes.
Ensure the device isn’t using an exit node with a configuration that prevents it from connecting to a local device.

If the device uses an exit node, it might not be able to access the private IP of the LAN device because the LAN is untrusted by default when using an exit node. You can resolve this with either of the following methods:
1. Pass --exit-node-allow-lan-access=true to the tailscale up or tailscale set commands.
2. Enable the Exit Node LAN access option in the Tailscale client (if applicable). This lets the device send LAN connections directly.
Only enable LAN access if you trust the local network. For example, you might trust your home network, but not a public access Wi-Fi at a coffee shop.

Poor network performance

This section provides troubleshooting guidance for poor network performance. Network performance problems often emerge as unstable connections, packet loss, high latency, or a failure to make a direct connection. The cause of these problems can differ depending on the context. As a result, this section is further divided into subsections for different types of connections, including connections between tailnet devices and connections to the internet.

Poor network performance between tailnet devices

The most common cause of performance issues between two tailnet devices is that Tailscale couldn’t establish direct connections between the two devices, so Tailscale connected them through a DERP relay server. DERP relay servers are how Tailscale circumvents NAT traversal problems to allow devices to connect when they otherwise wouldn’t have been able to do so. However, using a DERP relay server results in additional latency because the packets sent between the devices go through the DERP server before reaching their destination. DERP servers also limit throughput to ensure fairness between everyone using the DERP server.

Gather basic information about the connection between the two devices.

You can use the tailscale ping command to gather network information about the connection between two tailnet devices. The output shows useful information like whether a connection is possible, the latency in milliseconds, and the DERP servers used.

The output also indicates other information about the connection between the two devices. All tailnet connects start using a relayed connection and transition to a direct connection (if one is possible). However, it’s not always straightforward. For example, it might take a long time to establish a direct connection, or the devices might establish a direct connection and then revert to a relayed one.
Determine the connection types each device is using.

You can determine the connection types between two tailnet devices using the tailscale status command. Running the command lists all the connections and connection types between the current device and the other devices in the tailnet.

If the current device only uses relay connections, it likely can’t establish direct connections. If the current device uses direct and relay connections, it indicates that the NAT traversal problem likely originates from the other device.
Get a report of each device’s network conditions.

You can determine the network conditions of a device using the tailscale netcheck command. The command’s output includes useful information like whether the device supports UDP or port mapping and the latency information for the nearest DERP servers. Refer to troubleshooting with netcheck for more information and help interpreting the output.

If both devices use a direct connection and you didn’t uncover any problems with the tailscale ping, tailscale status, or tailscale netcheck commands, the issue might be the connection to the internet.

Poor network performance with connections to the internet

Use the following steps to help you troubleshoot why a device is experiencing network performance issues when connecting to the public internet.

Ensure the Tailscale client is up-to-date.

Make sure both devices are running the latest version of Tailscale. You can check the version of every device in your tailnet from the Machines page of the admin console.

You can also check the version of each device locally using the Tailscale application or the tailscale version command. This command also has flags available to check the version of the Tailscale client or the tailscaled daemon specifically.

If the Tailscale version is outdated, download and install the latest version.
Gather basic information about the device’s network configuration and connection to the website or device using a tool like ping, MTR, or traceroute (for macOS and Linux). For Windows, you can use ping, WinMTR, or tracert.
Check for Tailscale configurations that might prevent a connection.

If the device uses an exit node, ensure the exit node is online and has access to the resources you’re trying to access. For example, ensure that no access control policies prevent the exit node from reaching the destination’s IP address or port number. Additionally, ensure the exit node isn’t experiencing performance issues like latency.

If the device functions as an exit node, ensure its performance isn’t hindered by the inbound connections. You can do this by checking the bandwidth usage, the CPU usage, and the RAM usage.
Disconnect from any other virtual private network (VPN) software.

While Tailscale doesn’t deliberately conflict with other VPNs, it’s difficult to avoid conflicts in all environments. Many VPN programs also try to prevent other software, such as Tailscale, from making network configuration changes.
Disconnect from Tailscale. If the problem persists, continue troubleshooting basic network connectivity (beyond Tailscale).

Failure to resolve domain names

This section provides troubleshooting guidance for failure to resolve domain names. An inability to resolve domain names indicates a problem with the DNS. However, this could be an issue related to the local, network, or Tailscale DNS configurations. Use the following instructions to isolate why a device can’t resolve domain names.

Test the device's local DNS configuration to ensure you can resolve domain names. You should also check the device’s DNS configuration settings for invalid options. The location of these settings varies by operating system.

After testing your DNS configuration, disconnect Tailscale, then repeat your connection attempt to check if the problem is related to Tailscale.

If the device uses corporate or internet service provider (ISP) DNS servers, it might encounter problems with a feature called DNS rebinding protection when attempting to resolve private IP addresses. You can work around these problems using Tailscale DNS settings and MagicDNS.
Check the network DNS settings.

Make sure the upstream or network DNS configuration settings are valid. For example, ensure no incorrect IP addresses, typos, or syntax errors exist.

If the device is on-premise, you can find these settings on the default gateway (router) or the firewall. If the device is a cloud or virtual machine (VM), you can access the settings from the cloud provider (such as Amazon Web Services, Google Cloud, or Microsoft Azure).
Check Tailscale's DNS settings.

You can check if the device uses Tailscale's DNS settings from the Tailscale client.

If the client is set to use Tailscale’s DNS settings, verify the settings from the DNS page of the admin console. Make sure the device has permission to access the configured nameservers. For example, an access control policy could block its access or require the device to access the nameserver through a subnet router.

Basic network troubleshooting

Troubleshooting basic network connectivity varies by operating system, environment, and other variables. However, you might consider trying the following:

Gather basic information about the device’s network configuration and connection to the website or device.

The tools available to gather this information vary depending on the operating system.
macOS Windows Linux
On macOS devices, you can:
- Use a CLI tool like ping, ifconfig, or traceroute.
- Record a packet trace.
- Use a third-party tool like MTR or Wireshark.
Tool availability for other platforms and embedded systems might vary.
Check the device’s network configuration, such as the network interface card (NIC), subnet masks, default gateway, and DNS servers.
Check the device’s CPU and RAM usage.
Ensure there aren’t any physical problems with the device, such as worn cables or a low battery.
Check for updates to the device’s operating system or firmware.
Contact your internet service provider (ISP).
Restart the device.