Connector Failures

Connector and Remote Network Issues

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).

Common Symptoms:

• An entire set of Resources in a specific Remote Network (e.g., “AWS US-East-1 VPC”) becomes unreachable for all users and/or disappears from Clients.
• The Twingate Admin Console shows a Connector’s status as “Offline” or flapping intermittently between “Online” and “Offline.”
• Connector logs contain repeating errors like “Invalid token,” “failed to get an access token,” or “Gone, code 410.”
• Connector logs show “Failed to preconnect a relay listener” with a “Connection timed out” error.
• ICMP traffic (ping) to Resources behind a Connector fails, even though connections to other services succeed.

How to Identify and Troubleshoot:

• Use the Admin Console as Your Dashboard: The Connector details page is the single best place to check a Connector’s health.
  • Navigate to the Remote Network, click on the suspect Connector, and review its details.
  • Status: The most obvious check. If it’s “Offline,” the host is likely down or has lost internet connectivity.
  • Time Offset: This is a critical but subtle metric. Twingate’s authentication protocol is sensitive to clock skew. In the Connector details, check the Time Offset value. If the absolute value is greater than 5 seconds, the Connector’s system clock is out of sync with global time. This will cause its authentication tokens to be rejected by the Twingate Controller, resulting in “Invalid token” errors and a flapping status.
  • Resolution for Clock Drift: Ensure 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:
  • Ensure that the Connector was installed with the correct tokens. If tokens were regenerated in the Admin Console, the Connector must be reconfigured with the new tokens.
  • Verify that only one instance of the Connector is running with a given set of tokens. Running multiple Connectors with the same tokens will cause conflicts and connection failures.
  • Make sure the Connector software is up to date. Much older versions may have incompatibilities or be blocked.
  • Verify that the host machine meets the hardware and OS requirements for running a Connector.
  • Verify that the host OS allows outbound ICMP traffic if pinging Resources is required.
• Dive into Connector Logs: The logs provide the ground truth for what a Connector is experiencing.
  • You must enable detailed logging by setting TWINGATE_LOG_LEVEL=7.
  • For systemd deployments, view logs with journalctl -u twingate-connector -f. For Docker, use docker logs <container_name> -f.
  • Look for specific error patterns:
    • Invalid token: Almost always indicates a clock drift issue.
    • 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: This often indicates an outbound connectivity problem from the Connector host. It may be unable to reach Twingate’s Relay infrastructure, potentially due to a firewall or a lack of a public IPv4 address.
• Verify Connector Host Connectivity:
  • The host machine running the Connector must have outbound internet access to the Twingate infrastructure. Refer to the firewall requirements page for more information.
  • The host machine must have a network route to the private Resources it is intended to serve. A common error is deploying a Connector in a VPC subnet that has no route to the subnet where a database or application server resides.

If the Connector is online and healthy, but performance is poor or connections are unreliable, the problem is likely in the network path between the Client and the Connector.