The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 03:37 UTC
| 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. |