Troubleshooting

Twingate is a Zero Trust Network Access (ZTNA) solution designed to provide secure, direct access to your organization’s private applications and data, whether they are on-premises or in the cloud. Unlike traditional VPNs that grant broad network access and expose the network perimeter, Twingate operates on the principle of least privilege, making all Resources invisible by default and granting access only to authenticated and authorized Users for specific applications.

To effectively troubleshoot user issues, it’s essential to understand Twingate’s high-level architecture. The service is composed of four primary components that work in concert to secure every connection request:

• Client: The Twingate Client application runs on an end user’s device (Windows, macOS, Linux, iOS, Android). Its job is to intercept network traffic destined for protected Resources, handle user authentication, and establish secure, direct connections.
• Connectors: Connectors are lightweight software components deployed inside your private networks (e.g., in a VPC or an on-premises data center). They are deployed close to the Resources they protect and make outbound-only connections to the Twingate infrastructure, meaning you don’t need to open any inbound firewall ports.
• Relays: Relays are part of Twingate’s globally distributed public infrastructure. Their primary role is to facilitate the setup of a direct, peer-to-peer (P2P) connection between a Client and a Connector using a technique called NAT traversal. If a direct P2P connection cannot be established, Relays serve as a secure, high-performance backup channel for traffic.

A foundational concept for troubleshooting is the separation of the control plane and the data plane. The Controller (control plane) decides if a user should be allowed to connect. The Client, Connectors, and Relays (data plane) are responsible for how that connection is made. This distinction is vital: an access failure could be a policy issue (control plane) or a network connectivity issue (data plane). Understanding which plane is likely at fault is the first step toward rapid resolution.

For a more detailed architectural overview, please refer to the official How Twingate Works documentation.

The ZTNA Troubleshooting Mindset: Tracing the Path

Troubleshooting in a ZTNA world requires a shift in mindset from traditional network diagnostics. Because ZTNA solutions like Twingate are designed to make infrastructure invisible to unauthorized users, conventional tools like ping or tracert from an external network are often ineffective because there are no open inbound ports to probe. This “invisible infrastructure” is a powerful security feature, but it means that troubleshooting must shift from “probing the perimeter” to “interrogating the components.”

The key is to think of every successful connection as a chain of successful events. A user reporting an issue means there is a broken link somewhere in that chain. Your goal is to methodically trace the logical path of the connection to find that break.

The logical path of a Twingate connection unfolds in these stages:

• Identity & Authentication: The User authenticates against your configured Identity Provider (e.g., Okta, Entra ID, Google Workspace) to prove their identity.
• Device & Client: The Twingate Client on the user’s device, upon successful authentication, receives a signed Access Control List (ACL) from the Controller. This ACL is a user-specific list of authorized Resources, and also contains all routing information for each Resource.
• DNS Resolution: The user attempts to access a Resource by its name (e.g., server.corp.internal). The Twingate Client intercepts this DNS query on the local device.
• Routing & Connection Establishment: The Client, knowing this is a protected Resource, initiates a secure, encrypted tunnel to the appropriate Connector. This is ideally a direct peer-to-peer connection facilitated by NAT traversal.
• Connector to Resource: The Connector receives the encrypted traffic, decrypts it, and forwards it to the final destination Resource on the private network.

At each of these stages, Twingate evaluates the relevant Security Policy. A connection can be denied not just because of a technical failure but because a policy condition was not met. For example, the user’s device is not a trusted device, or they are connecting from a blocked geographical location. Therefore, troubleshooting must always consider both connectivity and policy.

Essential Tools and Resources

A successful troubleshooter uses the right tools for the job. Here is a consolidated list of the most important tools for diagnosing Twingate issues.

Twingate-Specific Tools

• Twingate Admin Console: Your primary command center. The most important sections for troubleshooting are:
  • Resource Activity Events (under Network > Overview): Shows real-time connection attempts and errors.
  • Connector Details (under Network > Connectors): Shows status, connection type (P2P vs. Relayed), and clock drift.
  • Audit Logs (under Settings > Reports > Audit Logs): Tracks all administrative changes to your Twingate configuration.
• Twingate Client Logs: Provides detailed logs from the user’s device. Users can enable detailed logging and upload logs to Twingate for diagnosis. See this guide for more information.
• Twingate Connector Logs: Provides detailed logs from the Connector host. Access them using Docker logs for container deployments or journalctl for systemd service deployments. See this guide for more information.

General Tools

• ping: For basic connectivity tests (e.g., from a Connector host to a private Resource).
• tracert / traceroute: To trace the network path to a public endpoint.
• nslookup / dig: Essential for diagnosing all DNS-related issues.
• ipconfig / ifconfig: To check a user’s local IP address, subnet, and DNS server configuration.
• nmap: A powerful network scanning tool useful for testing outbound port connectivity from a Client or Connector (e.g., nmap -p 30001 resource.internal to test access to a Resource by port).
• curl: A command-line tool for transferring data with URLs. It can be useful for testing API endpoints or checking the accessibility of Twingate Resources.
• Wireshark: A network protocol analyzer that can capture and display the data traveling back and forth on a network in real-time. It’s useful for diagnosing complex network issues. See this guide for more information.

A Repeatable Troubleshooting Methodology

Instead of taking a reactive, scattershot approach, follow a structured methodology to efficiently diagnose and resolve user issues. This four-step process helps isolate the fault domain and guides you to the root cause.

Step 1: Define the Scope (Isolate the Fault Domain)

Before diving into logs, gather information to understand the breadth and nature of the problem. This helps narrow down the potential causes significantly.

• One user vs. All users? If only one user is affected, the problem is likely specific to their identity, device, or local network. If all users are affected, the issue is more likely systemic, pointing toward a Connector, a Resource, or a global Twingate service issue.
• One Resource vs. All Resources? If only one Resource is inaccessible, the problem is likely with that Resource’s definition in Twingate, its host machine, or the specific Connector(s) responsible for it. If all Resources are inaccessible, the issue is more likely with the user’s Client, their network, or their identity.
• One location vs. All locations? If the issue only occurs when the user is on a specific network (e.g., their home Wi-Fi, a particular office), the problem is likely related to that network’s firewall or routing configuration.
• When did it start? Correlating the start of the issue with a recent change often expedites resolution.

Step 2: Check for Known States and Recent Changes

Once you have a scope, check for known issues or configuration changes that could explain the behavior.

• Check the Twingate Status Page: First, visit the official Twingate status page to see if there are any ongoing incidents with the Twingate service itself.

Step 3: Verify Identity and Device Posture

If there are no recent changes that would explain the issue, circle back to the control plane.

• Check User and Group Membership: In the Admin Console, verify the user is in the correct Group(s) that have been granted access to the Resource. Cross-reference this with your IdP to ensure group memberships are correctly synced.
• Check Device Posture: Review the Security Policy applied to the Resource. Does it require a Trusted Device? If so, navigate to the user’s device in the Admin Console and confirm its status meets the policy requirements.

Step 4: Trace the Connection Attempt

If the user has access to the Resource and their device meets all of the policy requirements, then this is the next investigative step. The Twingate Admin Console provides powerful tools to see what is happening on the data plane.

• Check the Resource Activity Report: This is the most valuable first diagnostic step. In the Admin Console, navigate to Network > Resources, select the Resource in question, and view the Activity section of the page.
  • No connection events: If you see no events logged for the user’s connection attempt, it means the traffic never reached the Connector. The problem is on the user’s side: an issue with the Client, their local network, or DNS lookups (such as being blocked by another security or DNS service on the device).
  • Events with “DNS lookup error”: This is a clear indicator that the Connector itself was unable to resolve the Resource’s hostname. The problem is with the DNS configuration on the Connector’s host machine or its ability to perform lookups with a configured resolver.
  • Events with “Unable to connect”: This indicates an issue on the local network, where the Connector was unable to route traffic to the destination system. This could be an issue with a firewall or switch, a security group, or that the system/application in question is blocking traffic from the Connector.
  • Successful connection events: If you see successful connection events but the user still reports a failure, the Twingate data path is working correctly. The issue is likely with the destination application, such as the user not having permissions to access it or doing something incorrectly that causes the application to refuse their connection.

If you’ve gone through all these troubleshooting steps and the issue is still unresolved, it may be time to escalate the issue to Twingate Support for further investigation.

You can open a support ticket in the Twingate Admin Console, by clicking Help > Support.

Diagnostic Quick Reference Table

Use this table to quickly map a user’s reported symptom to a likely cause and the first diagnostic step. It serves as a quick index to the more detailed pages.

Symptom Reported by User	Potential Failure Point (The Broken Link)	Primary Diagnostic Tool	First Question to Ask	Jump to Page
“I can’t log in to Twingate.” / “My password isn’t working.”	Authentication & Identity	Identity Provider Console (Okta, Entra ID, etc.)	Is the user active and assigned to the Twingate application in the IdP?	Identity Providers
“The Twingate app won’t connect.” / “It says the service isn’t running.”	Device or Client Application	Client Logs / OS Services (services.msc, launchctl)	Is the Twingate service/daemon running on the user’s machine?	Device or Client Failures
“I’m connected, but I can’t reach internal-app.company.internal.”	DNS Resolution	nslookup / dig (on Client) & Admin Console Activity	Can the user’s machine resolve the address? If not, does the Admin Console show a DNS error at the Connector?	DNS Resolution Problems
“No one can access the database server today.”	Connector & Remote Network	Admin Console (Connector Status & Details)	Are the Connectors for that Remote Network online and healthy? Is their clock in sync?	Connector Issues
“Everything feels really slow when I’m on Twingate.”	Firewall, NAT, & Routing	Admin Console (Connector Details)	Is the connection Peer-to-Peer or Relayed? Are outbound UDP ports blocked?	Firewall Issues
“I can’t print to my home printer when Twingate is on.”	Split Tunneling & IP Conflict	ipconfig / ifconfig & Admin Console (Resource Definitions)	Does a Twingate Resource definition (e.g., 192.168.1.0/24) overlap with the user’s local network?	Split Tunneling Issues

Additional Resources

If you’re looking for additional resources, please check the following:

• Review the Help Center: Start with the Self-Serve Troubleshooting Guide, which covers many common initial steps.
• Search the Knowledge Base: The Knowledge Base is an extensive repository of articles addressing specific errors, component configurations, and known incompatibilities.
• Consult the Community: For users on all plans, the Twingate subreddit is a valuable resource for asking questions and getting help from Twingate staff and other expert users.
• Engage Technical Support: For customers on eligible Teams, Business and Enterprise plans, Twingate offers ticketed technical support services. Before submitting a request, gather all relevant information, including the scope of the issue, affected users/Resources, and complete log bundles from the affected Client and/or Connector. You can learn how to open a request by reading the guide on Engaging Technical Support.