Connector Failures | Twingate

Connector Failures

How to troubleshoot common Connector issues including offline status, Resource connectivity, and performance

Connectors are the critical gateways to your private Resources. If a Connector is offline, misconfigured, or unhealthy, access to all Resources within its designated Remote Network will fail unless another working Connector is available on that Remote Network.

This page covers three common failure scenarios:

Connector is Offline or Flapping

A Connector that appears offline or repeatedly cycles between online and offline states is typically unable to communicate with the Twingate Controller or Relay infrastructure. All Resources on the affected Remote Network will be impacted.

Common Symptoms

Check the Admin Console

The Connector details page is the best starting point for diagnosing health issues. Navigate to the Remote Network, click on the suspect Connector, and review its details.

Clock drift is a common cause of flapping Connectors

If the Time Offset value is out of range, confirm the Connector’s host machine is running a time synchronization service. chronyd is generally recommended over the older ntpd. This is a host-level configuration, not a Twingate configuration.

Check Connector Host Configuration

Check Connector Logs

The logs provide the ground truth for what a Connector is experiencing. Enable detailed logging by setting TWINGATE_LOG_LEVEL=7.

For systemd deployments, view logs with:

journalctl -u twingate-connector -f

For Docker deployments, use:

docker logs <CONTAINER_NAME> -f

Replace <CONTAINER_NAME> with the name of the Connector container.

Look for these error patterns:

Error Likely Cause
Invalid token Clock drift on the Connector host. Check the Time Offset in the Admin Console.
too many open files The host system’s file descriptor limit (ulimit) is too low and needs to be increased.
Failed to preconnect a relay listener An outbound connectivity problem from the Connector host. It may be unable to reach Twingate’s Relay infrastructure due to a firewall rule or a lack of a public IPv4 address.

Verify Outbound Connectivity

The host machine running the Connector must have outbound internet access to the Twingate infrastructure. If outbound access is restricted, confirm the following are permitted:

Connector Cannot Reach Resources

A Connector may appear online and healthy in the Admin Console but still fail to forward traffic to one or more Resources. Users will see connection errors in the Client, and Connector logs will contain entries such as failed to connect or could not be reached for the affected Resource addresses.

Common Symptoms

Verify Network Reachability from the Connector Host

The Connector can only forward traffic to Resources that are routable from its host machine. SSH into the Connector host (or use docker exec for container deployments) and test connectivity to the Resource’s address and port directly.

Test TCP connectivity to a Resource:

nc -zv <RESOURCE_ADDRESS> <PORT>

Test DNS resolution of a Resource FQDN:

nslookup <RESOURCE_FQDN>

Replace <RESOURCE_ADDRESS>, <PORT>, and <RESOURCE_FQDN> with the values from the Resource configuration in the Admin Console.

If these tests fail from the Connector host itself, the issue is in the network path between the Connector and the Resource, not in Twingate.

Check Network Segmentation

A common misconfiguration is deploying a Connector in a VPC, VNet, or subnet that has no route to the subnet where the Resource resides. Verify the following:

Check Firewalls and Security Groups

Even when the Connector and Resource are on the same network, a firewall or cloud security group may block traffic between them. Verify the rules for your environment:

Check Application Level IP Filtering

Some services restrict connections to a specific set of allowed IP addresses. If the Resource runs a service with IP-based access controls, the Connector’s private IP address must be included in the allowlist. Common services to check:

To find the Connector’s private IP address, run the following on the Connector host:

hostname -I

Verify the Resource Configuration

Confirm that the address configured for the Resource in the Admin Console matches what is reachable from the Connector. If the Resource was defined using an FQDN, verify that the Connector’s host can resolve that name. If it was defined using an IP address, verify the address is correct and routable.

Also confirm that any port restrictions configured on the Resource match the ports the target service is listening on. By default, Twingate forwards traffic on all TCP and UDP ports, but if port restrictions have been applied to the Resource, only the specified ports will be forwarded.

Connector Is Online but Performance Is Poor

If the Connector is online and healthy but connections are slow or unreliable, the issue is likely in the network path between the Client and the Connector rather than in the Connector itself.

Check Peer-to-Peer Connectivity

Twingate routes traffic directly between the Client and the Connector whenever possible using peer-to-peer connections. If peer-to-peer cannot be established, traffic is relayed through Twingate’s Relay infrastructure, which may increase latency. Verify that both the Client’s network and the Connector’s network support the UDP connectivity required for peer-to-peer.

Common causes of poor performance include:

ICMP (Ping) Troubleshooting

If ping to Resources behind a Connector fails while other connections (SSH, HTTP, etc.) succeed, verify that the Connector’s host operating system allows outbound ICMP traffic. This is a host-level setting and is not controlled by Twingate.