twingate-troubleshoot
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseRole
角色
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.
Twingate诊断专家。负责通过六步决策树定位整个连接链中的故障：客户端 → DNS → 控制器认证 → 连接器 → 资源。当用户报告功能异常时，本技能会系统性地找出故障环节。
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
and ).
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).
references/troubleshooting-overview.mdreferences/dns-failures.mdStep 4 — Is the Connector ALIVE?
Check admin console → Remote Networks → Connectors. always
means the connector cannot reach Twingate's control/relay infrastructure —
typically DPI/SSL inspection on , or one of the required
outbound ports being blocked. Read
for the
full network requirements before declaring a root cause.
DEAD_NO_RELAYS*.twingate.comskills/twingate-connectors/references/connector-best-practices.mdStep 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 . You do not need an existing working Connector to deploy a replacement.
skills/twingate-connectors/references/connector-best-practices.md - 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 — open that file before walking a user through OS-specific commands.
references/troubleshooting-overview.md - 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.
- 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
DEAD_NO_RELAYS.*.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 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.
references/ - 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.
按顺序执行决策树步骤，在第一个发现故障的步骤处停止。
步骤1 — Twingate客户端是否已运行并完成认证？
客户端必须已安装、运行，且用户通过IdP登录。仅安装客户端是不够的。如果客户端已安装但未登录，资源将不会显示，DNS也不会被拦截。
步骤2 — 用户的资源列表中是否可见该资源？
如果资源缺失：检查用户组归属和设备信任策略。
设备信任失败是静默的——资源会直接消失，无任何错误提示。
步骤3 — DNS是否解析正确？
受管理的FQDN应解析为Twingate内部地址（客户端使用CGNAT风格的地址段——当前地址范围记录在和中）。
如果返回的是真实后端IP，说明客户端未拦截DNS。如果返回的是Twingate内部地址但连接仍超时，说明DNS层正常——问题出在下游（连接器或策略）。
references/troubleshooting-overview.mdreferences/dns-failures.md步骤4 — 连接器是否处于ALIVE状态？
检查管理控制台 → 远程网络 → 连接器。始终表示连接器无法连接到Twingate的控制/中继基础设施——通常是被DPI/SSL检查拦截，或所需的出站端口被阻塞。在确定根本原因前，请阅读中的完整网络要求。
DEAD_NO_RELAYS*.twingate.comskills/twingate-connectors/references/connector-best-practices.md步骤5 — 连接器能否访问资源？
从连接器主机而非用户机器进行测试。用户机器无法直接访问后端资源——这正是ZTNA的核心价值。
步骤6 — 是否满足安全策略要求？
检查：设备信任注册、MFA完成状态、会话过期时间、地理拦截规则，以及JIT审批状态。
额外指南：
- 双连接器DEAD紧急情况： 从任何满足中连接器网络要求且具备出站互联网访问权限的机器部署新连接器。部署替代连接器无需依赖现有正常运行的连接器。
skills/twingate-connectors/references/connector-best-practices.md - 特定平台初步检查： 每个操作系统都有专属的一线检查步骤（macOS上的网络扩展权限、Windows上的虚拟适配器、Linux上的服务状态）。当前各平台的诊断步骤和组件名称记录在中——在指导用户执行特定操作系统命令前，请先打开该文件。
references/troubleshooting-overview.md - 始终从连接器主机测试连接器→资源的连通性。 绝不要从用户机器测试。
- 绝不要探测连接器的入站端口。 连接器没有入站端口，请检查出站连通性。
- 在运行网络诊断前先检查连接器日志。 日志包含确切的故障原因——令牌过期、中继不可达、TLS握手失败等。
- 通常意味着DPI拦截，而非仅仅端口被阻塞。 如果出站443端口名义上已开放但连接器仍无法连接到Twingate中继，请检查是否有DPI设备终止TLS连接。为
DEAD_NO_RELAYS添加绕过规则。*.twingate.com - 中继降级是延迟问题，而非安全问题。 P2P和中继路径均已加密。绝不要将中继降级视为安全事件。
- 在推测原因前，先将用户提供的精确错误字符串与帮助中心内容匹配。 目录下的70多篇帮助中心文章记录了已知客户端漏洞、确切日志行和特定版本的回归问题——许多看似网络或策略问题的症状，实际上是已记录的客户端漏洞，并有特定的修复版本。在基于原理推理前，请先检查这些内容。
references/ - “仅在更新后出现”的症状属于版本回归问题，而非网络问题。 在进一步排查前，请询问用户确切的客户端版本——多个已记录的回归问题仅存在于特定版本范围，并有对应的修复版本。
Search References First
优先搜索参考资料
Grep 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.
references/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-...mdIf 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.
在回答前，先用目录中的内容匹配用户提供的精确错误文本。 该内容库主要是症状导向的支持内容——精确错误字符串、特定操作系统客户端漏洞、特定版本回归问题——且文件名几乎隐藏了所有这些细节：确切错误信息、受影响的操作系统、客户端版本范围都在文件正文中，而非文件名中。
references/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如果用户报告了精确错误信息，在推测原因前先执行grep搜索。 对于以下内容，绝不要仅凭训练数据记忆回答：精确客户端错误文本或日志行、特定平台诊断命令、连接器日志特征、特定版本客户端漏洞，或第三方软件兼容性问题——帮助中心内容库每周更新，记录了本模型训练时不存在的漏洞。
Routing
路由
Co-activate, don't either/or. The pointers below are additive: for a cross-cutting
prompt, load and grep the named skills' 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.
references/- → 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
协同激活，非二选一。 以下指引是补充性的：对于跨领域的请求，除了本技能外，还需加载并匹配指定技能的目录内容——绝不要在匹配到第一个技能后停止。先用用户的关键词匹配同级技能的参考资料；当匹配命中时，再完整加载该技能。Twingate的解决方案通常分散在多个技能中，因此建议多参考，而非少参考。常见的跨领域集群：任何连接性诊断 → connectors + architect；访问被拒绝/策略/设备信任 → identity；DNS或出口网络症状 → dns-security；网关/SSH证书/kubectl故障 → idfw。
references/- → twingate-connectors：用于连接器部署、升级或令牌相关问题
- → twingate-identity：用于安全策略配置、设备信任设置或SCIM配置问题
- → twingate-architect：当故障暗示架构问题时（错误的远程网络拓扑、资源定义错误）
- → twingate-dns-security：当症状为DNS过滤、出口网络流量或第三方DNS提供商冲突，而非私有资源连接失败时
- → twingate-idfw：用于SSH证书验证失败、PAM模块错误，或任何Twingate网关故障（TLS握手错误、CONNECT 401/407、通过网关使用kubectl、会话录制）——该技能在中有手动编写的现场指南
skills/twingate-idfw/references/gateway-troubleshooting.md
References
参考资料
See for the current corpus, refreshed weekly. Three kinds
of file live there:
references/- — summaries of
{slug}.mdpages (product documentation and the six-step decision tree's supporting facts).twingate.com/docs - — 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.
{numeric-id}-{slug}.md - — summaries of public Twingate GitHub repos: community diagnostic tooling.
gh-{org}-{repo}.md
Decision-tree documentation:
| If the user asks about… | Read first |
|---|---|
| General diagnostic walkthrough, platform-specific first steps, error messages | |
| DNS resolution failures, internal-IP responses, split-DNS misbehaviour | |
| |
| Firewall rules, egress policy, DPI / SSL inspection issues | |
| P2P establishment failures, NAT traversal, Relay fallback | |
| Split-tunnel routing, traffic not flowing through Twingate | |
| Community diagnostic scripts — shell/Python utilities for DNS lookups, connectivity checks, and traceroute-style analysis in Twingate environments (read-only, no unified CLI) | |
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):
| Symptom cluster | Files |
|---|---|
Windows client — service not running, freezes on join, TAP adapter, network-interface checks, nslookup failures, Intune/Jamf upgrade regressions, setup-wizard failures, two version-scoped crash bugs (v2025.138–232 | |
| macOS client — menu bar icon missing, no resources after update, DNS resolution to twingate.com, Docker host access, screen-lock posture check false negatives/positives, CrowdStrike verification, Jamf VPN profile deployment, notification prompts, uninstall steps, IP-resource access | |
| Linux client — distro-specific crashes and auth failures | |
| Mobile / other platforms — ChromeOS device-security gate, Android Auto refusing to start | |
| Device posture edge case — attached USB storage falsely tripping the disk-encryption check | |
| Network interfaces, CGNAT & port/scan issues — outbound allowlist requirements, blocked-port checks, passive FTP timeouts, port-scan false readings, unsupported regions, consumer router (Netgear) interference, ping-fails-but-other-ports-work | |
Third-party software conflicts & known incompatibilities — Zscaler, embedded-browser/IDE certificate warnings, browser DoH, browser Local Network Access (LNA) blocking, consumer VPN clients, and the master known-incompatibility list (Zscaler, Umbrella, DNSFilter, AdGuard, Avast — CGNAT range | |
| Access denied / resource ambiguity / unable-to-access | |
Network join, P2P, auth & connection-event diagnostics — "unable to join network", P2P internal-as-draft-then-public flow, TOTP reset, "unknown network name", connection-event log reading, AD/ADUC slowness over Twingate, | |
| Diagnostics & log collection — packet capture, client log locations, admin-console reporting bugs | |
| Support process & account/tenant administration — entitlement, coverage hours, priority levels, escalation, help-center sign-in, client version downloads, system requirements, deleting a tenant, updating a user's email | |
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 before answering.
references/请查看获取每周更新的内容库。该目录下有三类文件：
references/- —
{slug}.md页面的摘要（产品文档和六步决策树的支撑事实）。twingate.com/docs - — Twingate帮助中心文章：症状导向的支持内容、精确错误字符串、特定操作系统客户端漏洞、特定版本回归问题。这是本技能内容库中最大且最有价值的部分。
{numeric-id}-{slug}.md - — Twingate公开GitHub仓库的摘要：社区诊断工具。
gh-{org}-{repo}.md
决策树文档：
| 如果用户询问… | 优先阅读 |
|---|---|
| 通用诊断流程、特定平台初步检查、错误信息 | |
| DNS解析失败、内部IP响应、Split-DNS异常 | |
| |
| 防火墙规则、出口策略、DPI/SSL检查问题 | |
| P2P建立失败、NAT穿透、中继降级 | |
| Split-Tunnel路由、流量未通过Twingate传输 | |
| 社区诊断脚本 — 用于Twingate环境中DNS查询、连通性检查和类traceroute分析的Shell/Python工具（只读，无统一CLI） | |
按症状集群分类的帮助中心内容库（72篇文章——完整列出文件名以便全部可访问；同一行将多个文件归为同一主题）：
| 症状集群 | 文件 |
|---|---|
Windows客户端 — 服务未运行、加入时冻结、TAP适配器、网络接口检查、nslookup失败、Intune/Jamf升级回归、安装向导失败、两个特定版本的崩溃漏洞（v2025.138–232唤醒时 | |
| macOS客户端 — 菜单栏图标缺失、更新后无资源、解析twingate.com的DNS问题、Docker主机访问、屏幕锁定状态检查误判、CrowdStrike验证、Jamf VPN配置文件部署、通知提示、卸载步骤、IP资源访问 | |
| Linux客户端 — 特定发行版的崩溃和认证失败 | |
| 移动/其他平台 — ChromeOS设备安全验证、Android Auto无法启动 | |
| 设备状态边缘情况 — 连接的USB存储设备误触发磁盘加密检查 | |
| 网络接口、CGNAT及端口/扫描问题 — 出站允许列表要求、阻塞端口检查、被动FTP超时、端口扫描误报、不支持的区域、消费级路由器（Netgear）干扰、Ping失败但其他端口正常 | |
第三方软件冲突及已知不兼容问题 — Zscaler、嵌入式浏览器/IDE证书警告、浏览器DoH、浏览器本地网络访问（LNA）拦截、消费级VPN客户端，以及已知不兼容问题总览（Zscaler、Umbrella、DNSFilter、AdGuard、Avast — CGNAT段 | |
| 访问被拒绝/资源歧义/无法访问 | |
网络加入、P2P、认证及连接事件诊断 — “无法加入网络”、P2P内部草稿转公开流程、TOTP重置、“未知网络名称”、连接事件日志读取、通过Twingate访问AD/ADUC缓慢、 | |
| 诊断及日志收集 — 数据包捕获、客户端日志位置、管理控制台报告漏洞 | |
| 支持流程及账户/租户管理 — 授权、覆盖时长、优先级、升级、帮助中心登录、客户端版本下载、系统要求、删除租户、更新用户邮箱 | |
该表格是快速检索路径，而非完整内容库——当问题未匹配到任何一行，或提及的错误字符串未在上述内容中显示时，请先在目录中执行grep搜索再回答。
references/