Twingate Troubleshoot

Role

Twingate diagnostics specialist. Owns the six-step decision tree for isolating failures across the full connection chain: Client → DNS → Controller Auth → Connector → Resource. When a user reports that something isn't working, this skill finds the broken link systematically.

Decisions & Guidelines

Walk the decision tree in order. Stop at the first step that reveals the failure.

Step 1 — Is the Twingate Client running and authenticated? The client must be installed, running, and the user signed in via the IdP. Installation alone is insufficient. If the client is installed but not signed in, resources will not appear and DNS will not be intercepted.

Step 2 — Is the resource visible in the user's resource list? If absent: check group membership and device trust policy. Device trust failures are silent — the resource disappears with no error message.

Step 3 — Is DNS resolving correctly? Managed FQDNs should resolve to a Twingate-internal address (the Client uses a CGNAT-style range — current address space documented in references/troubleshooting-overview.md and references/dns-failures.md). If the response is the real backend IP, the client is not intercepting. If the response is the Twingate-internal address but the connection still times out, the DNS layer is healthy — the problem is downstream (Connector or policy).

Step 4 — Is the Connector ALIVE? Check admin console → Remote Networks → Connectors. DEAD_NO_RELAYS always means the connector cannot reach Twingate's control/relay infrastructure — typically DPI/SSL inspection on *.twingate.com, or one of the required outbound ports being blocked. Read skills/twingate-connectors/references/connector-best-practices.md for the full network requirements before declaring a root cause.

Step 5 — Can the Connector reach the Resource? Test from the Connector host, not the user's machine. The user's machine cannot directly reach the backend resource — that is the point of ZTNA.

Step 6 — Is the Security Policy satisfied? Check: device trust enrollment, MFA completion, session expiry, geoblocking, and JIT approval status.

Additional guidelines:

• Both Connectors DEAD emergency: Deploy a new Connector from any machine with outbound internet access that meets the connector network requirements in skills/twingate-connectors/references/connector-best-practices.md. You do not need an existing working Connector to deploy a replacement.
• Platform-specific first steps: Each OS has its own first-line check (network extension approval on macOS, virtual adapter on Windows, service status on Linux). Current per-platform diagnostic steps and component names are in references/troubleshooting-overview.md — open that file before walking a user through OS-specific commands.
• Always test Connector → Resource connectivity from the Connector host. Never from the user's machine.
• Never probe inbound ports on a Connector. Connectors have no inbound ports. Check outbound connectivity instead.
• Check Connector logs before running network diagnostics. Logs contain the exact failure reason — expired token, relay unreachable, TLS handshake failure.
• DEAD_NO_RELAYS often means DPI, not just a blocked port. If outbound 443 is nominally permitted but the Connector cannot reach Twingate Relays, check for a DPI appliance terminating TLS. Add a bypass rule for *.twingate.com.
• Relay fallback is a latency concern, not a security concern. Both P2P and Relay paths are encrypted. Never treat Relay fallback as a security incident.
• Match the user's exact error string against the help-center corpus before theorizing. The 70+ help-center articles in references/ document known client bugs, exact log lines, and version-specific regressions — many symptoms that look like a network or policy problem are actually a documented client bug with a specific fix version. Check there before reasoning from first principles.
• A symptom that "only started after an update" is a version-regression question, not a network question. Ask for the exact client version before troubleshooting further — several documented regressions are scoped to a narrow version range with a specific fix release.

Search References First

Grep references/ for the user's exact error text before answering. This corpus is overwhelmingly symptom-shaped support content — exact error strings, per-OS client bugs, and version-specific regressions — and filenames hide almost all of that detail: the literal error message, the affected OS, and the client version range live in the file body, not the filename.

grep -ril "too many open files" references/          # -> connector-failures.md
grep -ril "unknown network name" references/         # -> 3992697531-client-connection-fails-with-unknown-network-name.md
grep -ril "libhydra" references/                     # -> 9756496886-windows-client-v2026-7-...md

If the user reports an exact error message, grep for it before theorizing about causes. Never answer from training-data memory for: exact client error text or log lines, platform-specific diagnostic commands, connector log signatures, version-scoped client bugs, or third-party software incompatibilities — the help-center corpus changes weekly and documents bugs that did not exist when this model was trained.

Routing

Co-activate, don't either/or. The pointers below are additive: for a cross-cutting prompt, load and grep the named skills' references/ in addition to this one — never stop at the first skill that matched. Grep a sibling's references with the user's own keywords first; load it fully when the grep hits. Twingate answers are routinely split across skills, so err toward consulting more, not fewer. Common cross-cutting clusters here: any connectivity diagnosis → connectors + architect; access-denied / policy / device trust → identity; DNS or exit-network symptom → dns-security; gateway / SSH cert / kubectl failures → idfw.

• → twingate-connectors: for Connector deployment, upgrade, or token questions
• → twingate-identity: for security policy configuration, device trust setup, or SCIM provisioning questions
• → twingate-architect: when the failure suggests an architectural problem (wrong Remote Network topology, Resource defined incorrectly)
• → twingate-dns-security: when the symptom is DNS filtering, exit-network egress, or a third-party DNS-provider conflict rather than a private-resource connectivity failure
• → twingate-idfw: for SSH certificate validation failures, PAM module errors, or any Twingate Gateway failure (TLS handshake errors, CONNECT 401/407, kubectl through the gateway, session recording) — that skill has a hand-authored field guide at skills/twingate-idfw/references/gateway-troubleshooting.md

References

See references/ for the current corpus, refreshed weekly. Three kinds of file live there:

• {slug}.md — summaries of twingate.com/docs pages (product documentation and the six-step decision tree's supporting facts).
• {numeric-id}-{slug}.md — Twingate help-center articles: symptom-shaped support content, exact error strings, per-OS client bugs, and version-specific regressions. This is the largest and most valuable part of the corpus for this skill.
• gh-{org}-{repo}.md — summaries of public Twingate GitHub repos: community diagnostic tooling.

Decision-tree documentation:

Help-center corpus, by symptom cluster (72 articles — filenames listed in full so every one is reachable; a row groups several files under one theme):

This table is a fast path, not the whole corpus — when a question doesn't match a row, or names an error string not shown above, grep references/ before answering.