The best way to control Claude Code, Codex and more from any computer or phone

main
md 172 lines 9.12 KB
Rendered Raw
1 # T3 Connect troubleshooting
2
3 A T3 Connect connection goes through four parts, in this order:
4
5 1. **This device** reaches T3 Connect over the internet.
6 2. **T3 Connect** checks your sign-in and the host's link.
7 3. **The host's tunnel** (cloudflared on the host) carries the request to the host.
8 4. **T3 Code on the host** answers.
9
10 When a connection fails, open **Settings > Environments**, find the environment,
11 and select **Details**. The first part marked as failed is the cause. Find its
12 section below.
13
14 To see the host's side, run `t3 connect status` on the host, or open
15 **Settings > Sharing & access** on the host. Both check the host's T3 Connect
16 address from the host, and say why it fails. `t3 connect` runs the same check
17 when it finishes setup. This check cannot test another device's network. For a
18 problem on one device, use **Details** on that device.
19
20 ## The host's tunnel is offline
21
22 T3 Connect could not reach the host's tunnel. This means one of these:
23
24 - The host is asleep, turned off, or offline.
25 - T3 Code is not running on the host.
26 - The host's network blocks the tunnel. See
27 [Port 7844 is blocked on the host](#port-7844-is-blocked-on-the-host).
28
29 Fix:
30
31 1. Make sure the host is awake and T3 Code runs on it.
32 2. On the host, run `t3 connect status`. It names the problem on the host's side.
33 3. If the host was offline for a long time, T3 Connect removes its tunnel. Start
34 T3 Code on the host and update it to the latest version. It gets a new tunnel.
35
36 ## Port 7844 is blocked on the host
37
38 The tunnel on the host connects out to Cloudflare on port 7844, with TCP and
39 UDP. Both tunnel protocols (QUIC and HTTP/2) use this port. When the host's
40 network blocks it, the tunnel cannot start, but normal web traffic still works.
41 The host looks online, so this problem is easy to miss.
42
43 Common causes:
44
45 - **A Tailscale exit node on the host.** All of the host's internet traffic goes
46 through the exit node, and that network blocks port 7844. Turn off the exit
47 node on the host with `tailscale set --exit-node=`, or allow outbound port
48 7844 on the exit node's network.
49 - **A VPN on the host.** Work VPNs often block unknown ports. Ask for port 7844
50 to be allowed, or use a direct route instead (see below).
51 - **A firewall or strict network.** Allow outbound TCP and UDP port 7844.
52
53 If you cannot unblock the port, you can connect without T3 Connect. When the
54 host and this device are on the same Tailscale network, add the host's
55 Tailscale address as a direct route. See
56 [Reach one machine several ways](./remote-access.md#reach-one-machine-several-ways).
57
58 ## The tunnel works, but T3 Code does not answer
59
60 The host's tunnel is up, but it cannot reach T3 Code on the host. Common causes:
61
62 - T3 Code on the host stopped, crashed, or is still starting.
63 - T3 Code restarted on a different port, for example after an update, and the
64 tunnel still points at the old port.
65 - The server binds only one network address with `T3CODE_HOST`. The tunnel
66 sends requests to `127.0.0.1`, so the server must also listen there.
67
68 Fix: restart T3 Code on the host. For the background service, run
69 `t3 service restart`. Then run `t3 connect status` on the host.
70
71 ## The T3 Connect address does not resolve or answer
72
73 The host's T3 Connect address did not resolve, refused the connection, failed a
74 secure (TLS) connection, or did not answer in time.
75
76 Fix:
77
78 1. Make sure the host is awake and online.
79 2. On the host, run `t3 connect status`.
80 3. If the check fails only on the host, check the host's DNS, VPN, or proxy.
81 If it says the host's network has an old cached answer, wait: it usually
82 clears within about 30 minutes.
83 4. If it says the address no longer points to this machine's tunnel, the
84 environment was likely removed from T3 Connect. Link it again: on a desktop
85 host, turn **T3 Connect** off and on in **Settings > Sharing & access**. On a
86 command-line host, run `t3 connect link`, then restart T3 Code.
87
88 ## This device can't reach T3 Connect
89
90 The problem is on this device's network, not on the host. This device could
91 not reach T3 Connect, or it reached T3 Connect but not the host's tunnel
92 address.
93
94 Fix:
95
96 1. Check this device's internet connection. On a captive or dead Wi-Fi network,
97 the device can look online but cannot reach anything.
98 2. A VPN, firewall, ad blocker, or DNS filter on this device can block T3
99 Connect. Turn it off for a moment to test.
100 3. On iPhone, Connectivity Assist in the Wi-Fi settings can break T3 Connect.
101 Turn it off to test.
102 4. Try another network, or add a direct route to the host, such as its
103 Tailscale address. See
104 [Reach one machine several ways](./remote-access.md#reach-one-machine-several-ways).
105
106 ## Sign-in, account, or link problems
107
108 This device's T3 Connect sign-in is not ready yet, or T3 Connect does not have
109 an active link between your account and the host.
110
111 - **The host is linked to a different account.** Sign in to the same T3 Connect
112 account on this device and on the host. On the host, run `t3 connect logout`,
113 then `t3 connect`.
114 - **T3 Connect is off on the host, or the host only publishes agent activity.**
115 On the host, open **Settings > Sharing & access** and turn **T3 Connect** on, or
116 run `t3 connect`.
117 - **The host was linked, but the server did not apply the link yet.** Restart
118 the server on the host: quit and reopen the T3 Code desktop app, run
119 `t3 service restart`, or stop `t3 serve` and run it again.
120 - **This device's sign-in expired, or the host no longer accepts this
121 device.** Sign out of T3 Connect and sign in again.
122 - **This device is still loading its T3 Connect sign-in.** Wait a moment;
123 T3 Code retries on its own. If it keeps waiting, reload or restart T3 Code on
124 this device.
125 - **The host is waiting for you to approve this device.** The host requires
126 approval for new devices. Approve the code this device shows from a device
127 that is already connected, or run `t3 auth connect-device approve <code>` on
128 the host. See [Approve new devices](./remote-access.md#approve-new-devices).
129 - **Your account reached its tunnel limit.** Remove an environment you do not
130 use from your T3 account's T3 Connect page, or
131 [link a paid T3 Chat account](./remote-access.md#more-machines-with-t3-chat)
132 for a higher limit. Then restart T3 Code on the host.
133
134 ## The clock is off
135
136 T3 Connect signs requests with short-lived proofs. When the clock on this
137 device or the host is a few minutes wrong, T3 Connect rejects them. Turn on
138 automatic date and time on both devices, then retry.
139
140 ## The host runs an older T3 Code
141
142 This app needs a newer T3 Code on the host. Update T3 Code on the host. See
143 [Updating T3 Code](./updating.md).
144
145 ## T3 Connect returned an error
146
147 | Error | Fix |
148 | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
149 | `environment_link_limit_exceeded` or managed tunnel limit | Remove an unused environment or link a paid T3 Chat account, then restart T3 Code on the host. |
150 | `auth_invalid` or `invalid_bearer` | Run `t3 connect login`. If credentials were revoked, run `t3 connect logout`, then `t3 connect` again. Restart the server after signing in. |
151 | Expired or invalid link proof | Check the host's date and time, update T3 Code, then restart it. |
152 | HTTP 403 without a recognized error | If the host requires approval for new devices, update T3 Code on this device and approve it. Otherwise check relay access, proxies, and firewall rules. Keep any Cloudflare Ray ID for a bug report. |
153 | HTTP 408, 429, or 5xx | Wait a few minutes. T3 Code retries temporary failures on its own. |
154
155 After you fix a permanent rejection, restart the host's server with
156 `t3 service restart`. For a foreground server, stop it and run `t3 serve` again.
157
158 If T3 Code on the host disappears when SSH closes, see
159 [background-service troubleshooting](./background-service.md#troubleshooting).
160
161 ## Report a problem
162
163 If none of this helps, open an issue on
164 [GitHub](https://github.com/pingdotgg/t3code/issues). Include:
165
166 - The text from **Copy diagnostics** in the environment's **Details**.
167 - The output of `t3 connect status` on the host.
168 - The trace ID, if one is shown.
169 - If the tunnel dropped earlier, the host's tunnel log, `relay-client.ndjson`
170 in the logs folder (`~/.t3/userdata/logs` by default). It records when the
171 tunnel connected, warned, exited, and restarted, with the tunnel token
172 removed.