The best way to control Claude Code, Codex and more from any computer or phone
fix(server): T3 Connect says whether an unresolved address exists in public DNS (#34866)
Julius Marminge committed
Nov 11, 2026 at 23:40 UTC
0b6f482dc5d5ee64d7e90d1bac342756db9bfe68
3 files changed
+150
-24
apps/server/src/cloud/ConnectReachability.test.ts
+65
-3
@@ -13,7 +13,7 @@ import * as Layer from "effect/Layer";
13
import * as Queue from "effect/Queue";
14
import * as Stream from "effect/Stream";
15
import * as TestClock from "effect/testing/TestClock";
16
-import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
16
+import { HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse } from "effect/http";
17
import { ChildProcessSpawner } from "effect/process";
18
import { vi } from "vite-plus/test";
19
@@ -115,8 +115,10 @@ const cloudflareErrorPage = (request: HttpClientRequest.HttpClientRequest, code:
115
? JSON.stringify({ status: 530, error_code: code, error_name: "tunnel_error" })
116
: `<!doctype html><h1><span>Error</span> <span>${code}</span></h1>`;
117
118
+type Served = Effect.Effect<ServedResponse, HttpClientError.HttpClientError>;
119
+
120
const reachabilityLayer = (
119
- respond: Effect.Effect<ServedResponse>,
121
+ respond: Served | ((request: HttpClientRequest.HttpClientRequest) => Served),
122
restartConnector: (pid: number, stillDead: Effect.Effect<boolean>) => Effect.Effect<boolean>,
123
) =>
124
ConnectReachability.layer.pipe(
@@ -133,7 +135,7 @@ const reachabilityLayer = (
135
Layer.succeed(
136
HttpClient.HttpClient,
137
HttpClient.make((request) =>
136
- respond.pipe(
138
+ (Effect.isEffect(respond) ? respond : respond(request)).pipe(
139
Effect.map(({ status, body }) =>
140
HttpClientResponse.fromWeb(
141
request,
@@ -378,6 +380,66 @@ describe("ConnectReachability stale connector recovery", () => {
380
);
381
});
382
383
+describe("ConnectReachability DNS failures", () => {
384
+ // undici wraps getaddrinfo's error in `TypeError: fetch failed`. glibc behind
385
+ // systemd-resolved can report an NXDOMAIN as EBUSY rather than ENOTFOUND.
386
+ const lookupFailed = (code: string) =>
387
+ Effect.fail(
388
+ new HttpClientError.HttpClientError({
389
+ reason: new HttpClientError.TransportError({
390
+ request: HttpClientRequest.get("https://env.example.test"),
391
+ cause: new TypeError("fetch failed", {
392
+ cause: Object.assign(new Error(`getaddrinfo ${code} env.example.test`), {
393
+ code,
394
+ syscall: "getaddrinfo",
395
+ hostname: "env.example.test",
396
+ }),
397
+ }),
398
+ }),
399
+ }),
400
+ );
401
+
402
+ it.effect("reports a getaddrinfo EBUSY as a DNS failure", () =>
403
+ Effect.gen(function* () {
404
+ using _connect = mockEdgeConnect();
405
+ const layer = reachabilityLayer(lookupFailed("EBUSY"), () => Effect.succeed(false));
406
+ const result = yield* ConnectReachability.ConnectReachability.use(
407
+ (reachability) => reachability.check,
408
+ ).pipe(Effect.provide(layer));
409
+ expect(result).toMatchObject({ status: "unreachable", cause: "dns_failed" });
410
+ }),
411
+ );
412
+
413
+ // A local "not found" cached before the relay published the record looks like a missing
414
+ // record. Public DNS tells them apart.
415
+ it.effect("says whether the name exists in public DNS", () =>
416
+ Effect.gen(function* () {
417
+ using _connect = mockEdgeConnect();
418
+ for (const [lookupCode, dnsStatus, reason] of [
419
+ ["ENOTFOUND", 0, "old cached answer"],
420
+ ["ENOTFOUND", 3, "missing from public DNS"],
421
+ // The local resolver did not answer, so nothing it cached is to blame.
422
+ ["EAI_AGAIN", 0, "does not resolve from this machine"],
423
+ ] as const) {
424
+ const layer = reachabilityLayer(
425
+ (request) =>
426
+ request.url.startsWith("https://1.1.1.1/dns-query")
427
+ ? Effect.succeed({ status: 200, body: JSON.stringify({ Status: dnsStatus }) })
428
+ : lookupFailed(lookupCode),
429
+ () => Effect.succeed(false),
430
+ );
431
+ const result = yield* ConnectReachability.ConnectReachability.use(
432
+ (reachability) => reachability.check,
433
+ ).pipe(Effect.provide(layer));
434
+ expect(result).toMatchObject({
435
+ cause: "dns_failed",
436
+ reason: expect.stringContaining(reason),
437
+ });
438
+ }
439
+ }),
440
+ );
441
+});
442
+
443
describe("T3 Connect troubleshooting links", () => {
444
it("each section names a heading in the user guide", () => {
445
const guide = NodeFS.readFileSync(
apps/server/src/cloud/ConnectReachability.ts
+83
-21
@@ -17,7 +17,8 @@ import * as Ref from "effect/Ref";
17
import * as Scope from "effect/Scope";
18
import * as Stream from "effect/Stream";
19
import * as SynchronizedRef from "effect/SynchronizedRef";
20
-import { HttpClient } from "effect/http";
20
+import * as Schema from "effect/Schema";
21
+import { HttpClient, HttpClientResponse } from "effect/http";
22
import { ChildProcessSpawner } from "effect/process";
23
24
import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
@@ -31,6 +32,10 @@ const TUNNEL_EDGE_PORT = 7844;
32
const EDGE_CONNECT_TIMEOUT = Duration.seconds(5);
33
const ENDPOINT_REQUEST_TIMEOUT = Duration.seconds(10);
34
const ERROR_BODY_READ_TIMEOUT = Duration.seconds(2);
35
+// An IP literal, so the answer does not come from this machine's DNS, over HTTPS because
36
+// some networks intercept port 53.
37
+const PUBLIC_DNS_OVER_HTTPS = "https://1.1.1.1/dns-query";
38
+const PUBLIC_DNS_TIMEOUT = Duration.seconds(5);
39
// cloudflared registers several connections within a few seconds; they are one change.
40
const READINESS_CHANGE_DEBOUNCE = Duration.seconds(3);
41
// Readiness changes miss failures and recoveries past cloudflared (DNS, origin, edge errors).
@@ -43,7 +48,12 @@ const DEAD_CONNECTOR_RESTART_AFTER_MAX = Duration.hours(1);
48
49
export type EndpointProbe =
50
| { readonly kind: "status"; readonly status: number; readonly cloudflareError?: string }
46
- | { readonly kind: "dns_failed" | "timeout" | "network_error" };
51
+ | {
52
+ readonly kind: "dns_failed";
53
+ /** Whether public DNS has the name; absent when it could not be asked. */
54
+ readonly existsPublicly?: boolean;
55
+ }
56
+ | { readonly kind: "timeout" | "network_error" };
57
58
/** Everything one check learned. `null` means that step did not run. */
59
export interface ReachabilityFacts {
@@ -149,19 +159,37 @@ export function classifyReachability(
159
restart,
160
);
161
}
152
- return endpoint.kind === "dns_failed"
153
- ? fail(
162
+ if (endpoint.kind === "dns_failed") {
163
+ // A lookup made before the relay published the record leaves a cached "not found"
164
+ // for the zone's negative TTL (30 minutes).
165
+ if (endpoint.existsPublicly === true) {
166
+ return fail(
167
"dns_failed",
155
- "The T3 Connect address does not resolve from this machine.",
156
- "Check the DNS settings on this machine or its VPN.",
157
- exitNodeHint(exitNode),
158
- )
159
- : fail(
160
- "timeout",
161
- "The T3 Connect address did not answer from this machine.",
162
- "Check the network, VPN, or proxy on this machine.",
168
+ "The T3 Connect address resolves in public DNS, but this network's DNS still has an old cached answer that it does not exist.",
169
+ "Wait. The cached answer usually clears within about 30 minutes.",
170
exitNodeHint(exitNode),
171
);
172
+ }
173
+ if (endpoint.existsPublicly === false) {
174
+ return fail(
175
+ "dns_failed",
176
+ "The T3 Connect address is missing from public DNS. The relay did not publish it.",
177
+ restart,
178
+ );
179
+ }
180
+ return fail(
181
+ "dns_failed",
182
+ "The T3 Connect address does not resolve from this machine.",
183
+ "Check the DNS settings on this machine or its VPN.",
184
+ exitNodeHint(exitNode),
185
+ );
186
+ }
187
+ return fail(
188
+ "timeout",
189
+ "The T3 Connect address did not answer from this machine.",
190
+ "Check the network, VPN, or proxy on this machine.",
191
+ exitNodeHint(exitNode),
192
+ );
193
}
194
195
/** The loud diagnosis the CLI prints and the server logs. */
@@ -175,18 +203,25 @@ export function formatReachabilityFailure(result: Unreachable): string {
203
].join("\n");
204
}
205
178
-function hasErrorCode(error: unknown, codes: ReadonlySet<string>): boolean {
206
+/** The code of a failed name lookup, or null. getaddrinfo reports more than the DNS codes, such as EBUSY. */
207
+function dnsLookupErrorCode(error: unknown): string | null {
208
let current = error;
209
for (let depth = 0; depth < 6 && typeof current === "object" && current !== null; depth++) {
181
- if ("code" in current && typeof current.code === "string" && codes.has(current.code)) {
182
- return true;
210
+ const code = "code" in current && typeof current.code === "string" ? current.code : "";
211
+ if (("syscall" in current && current.syscall === "getaddrinfo") || DNS_ERROR_CODES.has(code)) {
212
+ return code;
213
}
214
current = "cause" in current ? current.cause : undefined;
215
}
186
- return false;
216
+ return null;
217
}
218
219
const DNS_ERROR_CODES = new Set(["ENOTFOUND", "EAI_AGAIN", "EAI_NONAME"]);
220
+// Answers that the name does not exist, which a resolver may have cached. EAI_AGAIN means
221
+// the resolver did not answer. glibc behind systemd-resolved can report NXDOMAIN as EBUSY.
222
+const NOT_FOUND_CODES = new Set(["ENOTFOUND", "EAI_NONAME", "EBUSY"]);
223
+
224
+const DnsJsonAnswer = Schema.Struct({ Status: Schema.Number });
225
226
const canOpenTcp = (host: string, port: number) =>
227
Effect.callback<boolean>((resume) => {
@@ -242,6 +277,22 @@ const make = Effect.gen(function* () {
277
Effect.orElseSucceed(() => null),
278
);
279
280
+ // DNS JSON status 0 is NOERROR (the name exists, even with no A record) and 3 is NXDOMAIN.
281
+ const existsInPublicDns = Effect.fn("ConnectReachability.existsInPublicDns")(
282
+ function* (hostname: string) {
283
+ const response = yield* httpClient.get(PUBLIC_DNS_OVER_HTTPS, {
284
+ urlParams: { name: hostname, type: "A" },
285
+ headers: { accept: "application/dns-json" },
286
+ });
287
+ const { Status } = yield* HttpClientResponse.schemaBodyJson(DnsJsonAnswer)(response);
288
+ return Status === 0 ? true : Status === 3 ? false : null;
289
+ },
290
+ Effect.scoped,
291
+ Effect.timeoutOption(PUBLIC_DNS_TIMEOUT),
292
+ Effect.map(Option.getOrNull),
293
+ Effect.orElseSucceed(() => null),
294
+ );
295
+
296
const probeEndpoint = Effect.fn("ConnectReachability.probeEndpoint")(
297
function* (hostname: string) {
298
const response = yield* httpClient
@@ -264,11 +315,22 @@ const make = Effect.gen(function* () {
315
) satisfies EndpointProbe;
316
},
317
Effect.scoped,
267
- Effect.catch((error) =>
268
- Effect.succeed<EndpointProbe>({
269
- kind: hasErrorCode(error, DNS_ERROR_CODES) ? "dns_failed" : "network_error",
270
- }),
271
- ),
318
+ (effect, hostname) =>
319
+ effect.pipe(
320
+ Effect.catch((error) => {
321
+ const code = dnsLookupErrorCode(error);
322
+ if (code === null) return Effect.succeed<EndpointProbe>({ kind: "network_error" });
323
+ if (!NOT_FOUND_CODES.has(code))
324
+ return Effect.succeed<EndpointProbe>({ kind: "dns_failed" });
325
+ return existsInPublicDns(hostname).pipe(
326
+ Effect.map((existsPublicly): EndpointProbe =>
327
+ existsPublicly === null
328
+ ? { kind: "dns_failed" }
329
+ : { kind: "dns_failed", existsPublicly },
330
+ ),
331
+ );
332
+ }),
333
+ ),
334
);
335
336
const gatherFacts = Effect.gen(function* () {
docs/user/t3-connect-troubleshooting.md
+2
@@ -78,6 +78,8 @@ Fix:
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
84
## This device can't reach T3 Connect
85