From 1c2698137a5645890bb1491203d984a0c40558e8 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Fri, 4 Sep 2026 14:07:57 -0700
Subject: [PATCH 1/3] fix(client): explain possible network blocking for T3
 Connect

---
 .../settings/ConnectionsSettings.tsx          |  4 +-
 .../src/authorization/service.ts              |  9 +++--
 .../src/connection/errors.test.ts             | 40 ++++++++++++++++++-
 .../client-runtime/src/connection/errors.ts   | 10 +++++
 .../src/connection/supervisor.test.ts         | 33 ++++++++++++++-
 .../src/connection/supervisor.ts              | 19 +++++++--
 packages/client-runtime/src/errors/network.ts |  4 ++
 .../src/relay/discovery.test.ts               |  3 +-
 .../src/relay/managedRelay.test.ts            | 32 ++++++++++++++-
 .../client-runtime/src/relay/managedRelay.ts  |  9 ++++-
 10 files changed, 150 insertions(+), 13 deletions(-)
 create mode 100644 packages/client-runtime/src/errors/network.ts

diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 1c4e034cf6a1..5a6f3ebd70b0 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1524,7 +1524,9 @@ function SavedBackendListRow({
           ) : null}
           {environment.connection.error && !resumingServerUpdate ? (
             <p className="flex min-w-0 items-center gap-2 text-destructive text-xs">
-              <span className="truncate">{connectionStatusText(environment.connection)}</span>
+              <span className="min-w-0 break-words">
+                {connectionStatusText(environment.connection)}
+              </span>
               {errorTraceId ? (
                 <button
                   type="button"
diff --git a/packages/client-runtime/src/authorization/service.ts b/packages/client-runtime/src/authorization/service.ts
index d918dcf0613d..fa17c288cbeb 100644
--- a/packages/client-runtime/src/authorization/service.ts
+++ b/packages/client-runtime/src/authorization/service.ts
@@ -80,9 +80,12 @@ function mapDpopSocketError(error: RemoteEnvironmentAuthError | ConnectionAttemp
 
 const fetchDescriptor = Effect.fn("clientRuntime.connection.remote.fetchDescriptor")(function* (
   httpBaseUrl: string,
+  connectionMethod: ClientConnectionMethod,
 ) {
   return yield* fetchRemoteEnvironmentDescriptor({ httpBaseUrl }).pipe(
-    Effect.mapError(mapRemoteEnvironmentError),
+    Effect.mapError(
+      connectionMethod === "relay" ? mapRemoteDpopEnvironmentError : mapRemoteEnvironmentError,
+    ),
   );
 });
 
@@ -119,7 +122,7 @@ export const make = Effect.gen(function* () {
         cachedDescriptor.validatedAtEpochMs + BEARER_DESCRIPTOR_CACHE_TTL_MS > now;
       const descriptor = canReuseDescriptor
         ? cachedDescriptor.descriptor
-        : yield* fetchDescriptor(input.httpBaseUrl).pipe(
+        : yield* fetchDescriptor(input.httpBaseUrl, input.connectionMethod).pipe(
             Effect.provideService(HttpClient.HttpClient, httpClient),
           );
       if (descriptor.environmentId !== input.expectedEnvironmentId) {
@@ -252,7 +255,7 @@ export const make = Effect.gen(function* () {
         "connection.remote_token_cache": "miss",
       });
       const bootstrap = yield* input.obtainBootstrap;
-      const descriptor = yield* fetchDescriptor(bootstrap.endpoint.httpBaseUrl).pipe(
+      const descriptor = yield* fetchDescriptor(bootstrap.endpoint.httpBaseUrl, "relay").pipe(
         Effect.provideService(HttpClient.HttpClient, httpClient),
         Effect.withSpan("environment.authorization.descriptor"),
       );
diff --git a/packages/client-runtime/src/connection/errors.test.ts b/packages/client-runtime/src/connection/errors.test.ts
index 771c9490ca3e..0e760bc8f12a 100644
--- a/packages/client-runtime/src/connection/errors.test.ts
+++ b/packages/client-runtime/src/connection/errors.test.ts
@@ -1,12 +1,36 @@
 import { EnvironmentAuthInvalidError } from "@t3tools/contracts";
-import { RelayAuthInvalidError } from "@t3tools/contracts/relay";
+import {
+  RelayAuthInvalidError,
+  RelayEnvironmentEndpointTimedOutError,
+} from "@t3tools/contracts/relay";
 import { describe, expect, it } from "@effect/vitest";
 
 import { mapManagedRelayError, mapRemoteDpopEnvironmentError } from "./errors.ts";
 import { DPOP_RETRY_HINT, DPOP_UNKNOWN_HINT } from "../relay/errorPresentation.ts";
 import { ManagedRelayRequestFailedError } from "../relay/managedRelay.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
+import { RemoteEnvironmentAuthFetchError, RemoteEnvironmentAuthTimeoutError } from "../rpc/http.ts";
 
 describe("mapManagedRelayError", () => {
+  it("keeps a timeout reported by the relay distinct from a local network failure", () => {
+    const relayError = new RelayEnvironmentEndpointTimedOutError({
+      code: "environment_endpoint_timed_out",
+      traceId: "trace-server-timeout",
+    });
+    const mapped = mapManagedRelayError(
+      new ManagedRelayRequestFailedError({
+        action: "connect relay environment",
+        cause: relayError,
+        relayError,
+      }),
+    );
+    expect(mapped).toMatchObject({
+      reason: "timeout",
+      detail: "Relay timed out while contacting the environment endpoint.",
+      traceId: "trace-server-timeout",
+    });
+  });
+
   it("presents clock skew as one possible cause for a generic DPoP error", () => {
     const mapped = mapManagedRelayError(
       new ManagedRelayRequestFailedError({
@@ -48,6 +72,20 @@ describe("mapManagedRelayError", () => {
 });
 
 describe("mapRemoteDpopEnvironmentError", () => {
+  it.each([
+    new RemoteEnvironmentAuthFetchError({
+      message: "Failed to fetch remote environment endpoint.",
+      cause: new TypeError("Failed to fetch"),
+    }),
+    new RemoteEnvironmentAuthTimeoutError("https://environment.example.test", 10_000),
+  ])("suggests another network when the relay endpoint cannot be reached: $_tag", (error) => {
+    const mapped = mapRemoteDpopEnvironmentError(error);
+    expect(mapped).toMatchObject({
+      _tag: "ConnectionTransientError",
+      detail: `${error.message} ${NETWORK_BLOCKING_HINT}`,
+    });
+  });
+
   it("does not present a generic environment auth error as confirmed clock skew", () => {
     const mapped = mapRemoteDpopEnvironmentError(
       new EnvironmentAuthInvalidError({
diff --git a/packages/client-runtime/src/connection/errors.ts b/packages/client-runtime/src/connection/errors.ts
index ed8a117a6f5c..b026f1ae89a3 100644
--- a/packages/client-runtime/src/connection/errors.ts
+++ b/packages/client-runtime/src/connection/errors.ts
@@ -3,6 +3,7 @@ import type { RelayProtectedError } from "@t3tools/contracts/relay";
 import type { ManagedRelayClientError } from "../relay/managedRelay.ts";
 import { dpopFailureMessage, relayProtectedErrorMessage } from "../relay/errorPresentation.ts";
 import type { RemoteEnvironmentAuthError } from "../authorization/remote.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 import {
   ConnectionBlockedError,
   type ConnectionAttemptError,
@@ -178,6 +179,15 @@ export function mapRemoteEnvironmentError(
 export function mapRemoteDpopEnvironmentError(
   error: RemoteEnvironmentAuthError,
 ): ConnectionAttemptError {
+  if (
+    error._tag === "RemoteEnvironmentAuthFetchError" ||
+    error._tag === "RemoteEnvironmentAuthTimeoutError"
+  ) {
+    return new ConnectionTransientError({
+      reason: error._tag === "RemoteEnvironmentAuthFetchError" ? "network" : "timeout",
+      detail: `${error.message} ${NETWORK_BLOCKING_HINT}`,
+    });
+  }
   if (error._tag === "EnvironmentAuthInvalidError" && error.reason === "invalid_credential") {
     return new ConnectionBlockedError({
       reason: "authentication",
diff --git a/packages/client-runtime/src/connection/supervisor.test.ts b/packages/client-runtime/src/connection/supervisor.test.ts
index 8f38633d55f6..64b90b5bb3ed 100644
--- a/packages/client-runtime/src/connection/supervisor.test.ts
+++ b/packages/client-runtime/src/connection/supervisor.test.ts
@@ -30,6 +30,7 @@ import {
 import * as RpcSession from "../rpc/session.ts";
 import * as EnvironmentSupervisor from "./supervisor.ts";
 import * as ConnectionWakeups from "./wakeups.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 const TARGET = new PrimaryConnectionTarget({
   environmentId: EnvironmentId.make("environment-1"),
@@ -243,10 +244,11 @@ describe("EnvironmentSupervisor", () => {
         Effect.provideService(RelayClientTracer, Option.some(tracer)),
       );
 
-      yield* awaitState(
+      const failed = yield* awaitState(
         supervisor.state,
         (state) => state.phase === "backoff" && state.attempt === 1,
       );
+      expect(failed.lastFailure?.message).toBe(`Connection failed. ${NETWORK_BLOCKING_HINT}`);
       const firstAttempt = spans.find((span) => span.name === "relay.connection.attempt");
       expect(firstAttempt).toBeDefined();
 
@@ -467,6 +469,35 @@ describe("EnvironmentSupervisor", () => {
     }).pipe(Effect.provide(TestClock.layer())),
   );
 
+  it.effect(
+    "shows a network hint for a stalled relay connection and clears it after recovery",
+    () =>
+      Effect.gen(function* () {
+        const harness = yield* makeHarness({
+          prepare: (attempt) =>
+            attempt === 1 ? Effect.never : Effect.succeed(PREPARED_CONNECTION),
+        });
+        const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
+          initiallyDesired: true,
+        }).pipe(Effect.provide(harness.dependencies));
+
+        yield* awaitState(supervisor.state, (state) => state.phase === "connecting");
+        yield* TestClock.adjust("15 seconds");
+        const failed = yield* awaitState(supervisor.state, (state) => state.phase === "backoff");
+        expect(failed.lastFailure?.message).toBe(
+          `Test environment did not respond during connection setup. ${NETWORK_BLOCKING_HINT}`,
+        );
+
+        yield* TestClock.adjust("3 seconds");
+        const recovered = yield* awaitState(
+          supervisor.state,
+          (state) => state.phase === "connected",
+        );
+        expect(recovered.lastFailure).toBeNull();
+        expect(yield* Ref.get(harness.prepareCount)).toBe(2);
+      }).pipe(Effect.provide(TestClock.layer())),
+  );
+
   it.effect("converts unexpected driver defects into retryable failures", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness({
diff --git a/packages/client-runtime/src/connection/supervisor.ts b/packages/client-runtime/src/connection/supervisor.ts
index 9d5452344499..a8f1ee10e618 100644
--- a/packages/client-runtime/src/connection/supervisor.ts
+++ b/packages/client-runtime/src/connection/supervisor.ts
@@ -28,6 +28,7 @@ import {
 } from "./model.ts";
 import * as RpcSession from "../rpc/session.ts";
 import { safeErrorLogAttributes } from "../errors/safeLog.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 import * as ConnectionWakeups from "./wakeups.ts";
 
 const RETRY_DELAYS_MS = [3_000, 4_000, 8_000, 16_000] as const;
@@ -241,6 +242,9 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
   | ConnectionWakeups.ConnectionWakeups
 > {
   const target = entry.target;
+  const setupTimeoutDetail = `${target.label} did not respond during connection setup.${
+    target._tag === "RelayConnectionTarget" ? ` ${NETWORK_BLOCKING_HINT}` : ""
+  }`;
   yield* annotateTarget(target);
 
   const connectivity = yield* Connectivity.Connectivity;
@@ -626,7 +630,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       } else {
         replacementError = new ConnectionTransientError({
           reason: "timeout",
-          detail: `${target.label} did not respond during connection setup.`,
+          detail: setupTimeoutDetail,
         });
       }
 
@@ -708,7 +712,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
         failure: {
           error: new ConnectionTransientError({
             reason: "timeout",
-            detail: `${target.label} did not respond during connection setup.`,
+            detail: setupTimeoutDetail,
           }),
           attemptSpan: Option.none(),
         },
@@ -912,7 +916,16 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       }
 
       const attemptSpan: Option.Option<Tracer.Span> = outcome.failure.attemptSpan;
-      const error: ConnectionAttemptError = outcome.failure.error;
+      const failure: ConnectionAttemptError = outcome.failure.error;
+      const error: ConnectionAttemptError =
+        target._tag === "RelayConnectionTarget" &&
+        failure._tag === "ConnectionTransientError" &&
+        failure.reason === "transport"
+          ? new ConnectionTransientError({
+              ...failure,
+              detail: `${failure.message} ${NETWORK_BLOCKING_HINT}`,
+            })
+          : failure;
       latestFailure = error;
       if (error._tag === "ConnectionBlockedError") {
         const blockedIntent = yield* Ref.get(intent);
diff --git a/packages/client-runtime/src/errors/network.ts b/packages/client-runtime/src/errors/network.ts
new file mode 100644
index 000000000000..1e726bdd4d98
--- /dev/null
+++ b/packages/client-runtime/src/errors/network.ts
@@ -0,0 +1,4 @@
+// A failed request cannot distinguish filtering from an outage. Keep this a
+// possible cause, and suggest a way to check without changing server settings.
+export const NETWORK_BLOCKING_HINT =
+  "Your DNS or firewall may be blocking T3 Connect. Try another network, such as a phone hotspot.";
diff --git a/packages/client-runtime/src/relay/discovery.test.ts b/packages/client-runtime/src/relay/discovery.test.ts
index 8cb963000bd3..36dacf82648a 100644
--- a/packages/client-runtime/src/relay/discovery.test.ts
+++ b/packages/client-runtime/src/relay/discovery.test.ts
@@ -19,6 +19,7 @@ import * as Connectivity from "../connection/connectivity.ts";
 import { ConnectionBlockedError, type NetworkStatus } from "../connection/model.ts";
 import * as ConnectionWakeups from "../connection/wakeups.ts";
 import * as RelayEnvironmentDiscovery from "./discovery.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 const environments = [
   {
@@ -305,7 +306,7 @@ describe("RelayEnvironmentDiscovery", () => {
         expect(Option.getOrThrow(state.error)).toMatchObject({
           _tag: "ConnectionTransientError",
           reason: "timeout",
-          message: "Relay environment listing timed out.",
+          message: `Relay environment listing timed out. ${NETWORK_BLOCKING_HINT}`,
         });
       }).pipe(Effect.provide(layer));
     }),
diff --git a/packages/client-runtime/src/relay/managedRelay.test.ts b/packages/client-runtime/src/relay/managedRelay.test.ts
index 4cba8064f207..69cb200625bc 100644
--- a/packages/client-runtime/src/relay/managedRelay.test.ts
+++ b/packages/client-runtime/src/relay/managedRelay.test.ts
@@ -13,6 +13,7 @@ import * as TestClock from "effect/testing/TestClock";
 
 import * as ManagedRelay from "./managedRelay.ts";
 import { remoteHttpClientLayer } from "../rpc/http.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 function managedRelayTestLayer(
   fetchFn: typeof globalThis.fetch,
@@ -529,11 +530,40 @@ describe("ManagedRelayClient", () => {
         _tag: "ManagedRelayRequestTimeoutError",
         activity: "Relay environment listing",
         timeoutMs: ManagedRelay.MANAGED_RELAY_REQUEST_TIMEOUT_MS,
-        message: "Relay environment listing timed out.",
+        message: `Relay environment listing timed out. ${NETWORK_BLOCKING_HINT}`,
       });
     }).pipe(Effect.provide(Layer.merge(TestClock.layer(), managedRelayTestLayer(fetchFn))));
   });
 
+  it.effect("suggests checking network filtering when fetch fails without a response", () => {
+    const fetchFn = (() =>
+      Promise.reject(new TypeError("Failed to fetch"))) satisfies typeof globalThis.fetch;
+    return Effect.gen(function* () {
+      const relayClient = yield* ManagedRelay.ManagedRelayClient;
+      const error = yield* relayClient
+        .listEnvironments({ clerkToken: "clerk-token" })
+        .pipe(Effect.flip);
+      expect(error).toMatchObject({
+        _tag: "ManagedRelayRequestFailedError",
+        message: `Could not list relay-managed environments. ${NETWORK_BLOCKING_HINT}`,
+      });
+    }).pipe(Effect.provide(managedRelayTestLayer(fetchFn)));
+  });
+
+  it.effect("does not suggest network filtering for an HTTP server error", () => {
+    const fetchFn = (() =>
+      Promise.resolve(
+        new Response("Unavailable", { status: 503 }),
+      )) satisfies typeof globalThis.fetch;
+    return Effect.gen(function* () {
+      const relayClient = yield* ManagedRelay.ManagedRelayClient;
+      const error = yield* relayClient
+        .listEnvironments({ clerkToken: "clerk-token" })
+        .pipe(Effect.flip);
+      expect(error.message).toBe("Could not list relay-managed environments.");
+    }).pipe(Effect.provide(managedRelayTestLayer(fetchFn)));
+  });
+
   it.effect("preserves typed relay trace IDs on client errors", () => {
     const fetchFn = (() =>
       Promise.resolve(
diff --git a/packages/client-runtime/src/relay/managedRelay.ts b/packages/client-runtime/src/relay/managedRelay.ts
index d74130322619..7cc04fcd9603 100644
--- a/packages/client-runtime/src/relay/managedRelay.ts
+++ b/packages/client-runtime/src/relay/managedRelay.ts
@@ -44,6 +44,7 @@ import * as SynchronizedRef from "effect/SynchronizedRef";
 import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import type * as HttpMethod from "effect/unstable/http/HttpMethod";
 import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 export interface ManagedRelayDpopProofInput {
   readonly method: HttpMethod.HttpMethod;
@@ -126,7 +127,7 @@ export class ManagedRelayRequestTimeoutError extends Schema.TaggedErrorClass<Man
   },
 ) {
   override get message(): string {
-    return `${this.activity} timed out.`;
+    return `${this.activity} timed out. ${NETWORK_BLOCKING_HINT}`;
   }
 }
 
@@ -151,7 +152,11 @@ export class ManagedRelayRequestFailedError extends Schema.TaggedErrorClass<Mana
   },
 ) {
   override get message(): string {
-    return `Could not ${this.action}.`;
+    const message = `Could not ${this.action}.`;
+    return HttpClientError.isHttpClientError(this.cause) &&
+      this.cause.reason._tag === "TransportError"
+      ? `${message} ${NETWORK_BLOCKING_HINT}`
+      : message;
   }
 }
 

From 8f3106f83edff3e90d2cccd8c3de814dbc4daca4 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Fri, 4 Sep 2026 14:19:28 -0700
Subject: [PATCH 2/3] fix(client): classify network failures at transport
 boundaries

---
 .../src/connection/supervisor.test.ts         |  5 +-
 .../src/connection/supervisor.ts              | 11 +---
 .../src/relay/managedRelay.test.ts            |  8 +++
 .../client-runtime/src/relay/managedRelay.ts  |  8 +--
 .../client-runtime/src/rpc/session.test.ts    | 54 +++++++++++--------
 packages/client-runtime/src/rpc/session.ts    | 25 ++++++---
 6 files changed, 66 insertions(+), 45 deletions(-)

diff --git a/packages/client-runtime/src/connection/supervisor.test.ts b/packages/client-runtime/src/connection/supervisor.test.ts
index 64b90b5bb3ed..f532e504605a 100644
--- a/packages/client-runtime/src/connection/supervisor.test.ts
+++ b/packages/client-runtime/src/connection/supervisor.test.ts
@@ -244,11 +244,10 @@ describe("EnvironmentSupervisor", () => {
         Effect.provideService(RelayClientTracer, Option.some(tracer)),
       );
 
-      const failed = yield* awaitState(
+      yield* awaitState(
         supervisor.state,
         (state) => state.phase === "backoff" && state.attempt === 1,
       );
-      expect(failed.lastFailure?.message).toBe(`Connection failed. ${NETWORK_BLOCKING_HINT}`);
       const firstAttempt = spans.find((span) => span.name === "relay.connection.attempt");
       expect(firstAttempt).toBeDefined();
 
@@ -506,7 +505,7 @@ describe("EnvironmentSupervisor", () => {
             ? Effect.die(new Error("Native transport defect."))
             : Effect.succeed(PREPARED_CONNECTION),
       });
-      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+      const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
         initiallyDesired: true,
       }).pipe(Effect.provide(harness.dependencies));
 
diff --git a/packages/client-runtime/src/connection/supervisor.ts b/packages/client-runtime/src/connection/supervisor.ts
index a8f1ee10e618..0ff7b247a163 100644
--- a/packages/client-runtime/src/connection/supervisor.ts
+++ b/packages/client-runtime/src/connection/supervisor.ts
@@ -916,16 +916,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       }
 
       const attemptSpan: Option.Option<Tracer.Span> = outcome.failure.attemptSpan;
-      const failure: ConnectionAttemptError = outcome.failure.error;
-      const error: ConnectionAttemptError =
-        target._tag === "RelayConnectionTarget" &&
-        failure._tag === "ConnectionTransientError" &&
-        failure.reason === "transport"
-          ? new ConnectionTransientError({
-              ...failure,
-              detail: `${failure.message} ${NETWORK_BLOCKING_HINT}`,
-            })
-          : failure;
+      const error: ConnectionAttemptError = outcome.failure.error;
       latestFailure = error;
       if (error._tag === "ConnectionBlockedError") {
         const blockedIntent = yield* Ref.get(intent);
diff --git a/packages/client-runtime/src/relay/managedRelay.test.ts b/packages/client-runtime/src/relay/managedRelay.test.ts
index 69cb200625bc..2699c4ad0803 100644
--- a/packages/client-runtime/src/relay/managedRelay.test.ts
+++ b/packages/client-runtime/src/relay/managedRelay.test.ts
@@ -9,12 +9,16 @@ import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
 import * as Tracer from "effect/Tracer";
+import * as Schema from "effect/Schema";
 import * as TestClock from "effect/testing/TestClock";
 
 import * as ManagedRelay from "./managedRelay.ts";
 import { remoteHttpClientLayer } from "../rpc/http.ts";
 import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
+const encodeRelayError = Schema.encodeEffect(ManagedRelay.ManagedRelayClientError);
+const decodeRelayError = Schema.decodeUnknownEffect(ManagedRelay.ManagedRelayClientError);
+
 function managedRelayTestLayer(
   fetchFn: typeof globalThis.fetch,
   relayUrl = "https://relay.example.test",
@@ -545,8 +549,12 @@ describe("ManagedRelayClient", () => {
         .pipe(Effect.flip);
       expect(error).toMatchObject({
         _tag: "ManagedRelayRequestFailedError",
+        transportFailed: true,
         message: `Could not list relay-managed environments. ${NETWORK_BLOCKING_HINT}`,
       });
+      const encoded = yield* encodeRelayError(error);
+      const decoded = yield* decodeRelayError(encoded);
+      expect(decoded.message).toBe(error.message);
     }).pipe(Effect.provide(managedRelayTestLayer(fetchFn)));
   });
 
diff --git a/packages/client-runtime/src/relay/managedRelay.ts b/packages/client-runtime/src/relay/managedRelay.ts
index 7cc04fcd9603..d9f81c356e22 100644
--- a/packages/client-runtime/src/relay/managedRelay.ts
+++ b/packages/client-runtime/src/relay/managedRelay.ts
@@ -146,6 +146,7 @@ export class ManagedRelayRequestFailedError extends Schema.TaggedErrorClass<Mana
   "ManagedRelayRequestFailedError",
   {
     action: ManagedRelayRequestAction,
+    transportFailed: Schema.optionalKey(Schema.Boolean),
     cause: Schema.Defect(),
     relayError: Schema.optional(RelayProtectedError),
     traceId: Schema.optional(Schema.String),
@@ -153,10 +154,7 @@ export class ManagedRelayRequestFailedError extends Schema.TaggedErrorClass<Mana
 ) {
   override get message(): string {
     const message = `Could not ${this.action}.`;
-    return HttpClientError.isHttpClientError(this.cause) &&
-      this.cause.reason._tag === "TransportError"
-      ? `${message} ${NETWORK_BLOCKING_HINT}`
-      : message;
+    return this.transportFailed ? `${message} ${NETWORK_BLOCKING_HINT}` : message;
   }
 }
 
@@ -312,6 +310,8 @@ function relayRequestError(action: ManagedRelayRequestAction) {
   return (cause: RelayHttpRequestError): ManagedRelayClientError =>
     new ManagedRelayRequestFailedError({
       action,
+      transportFailed:
+        HttpClientError.isHttpClientError(cause) && cause.reason._tag === "TransportError",
       cause,
       ...(isRelayProtectedError(cause) ? { relayError: cause, traceId: cause.traceId } : {}),
     });
diff --git a/packages/client-runtime/src/rpc/session.test.ts b/packages/client-runtime/src/rpc/session.test.ts
index f8f940bc551f..3521464fed68 100644
--- a/packages/client-runtime/src/rpc/session.test.ts
+++ b/packages/client-runtime/src/rpc/session.test.ts
@@ -29,6 +29,7 @@ import {
   ConnectionBlockedError,
   ConnectionTransientError,
   PrimaryConnectionTarget,
+  RelayConnectionTarget,
   type PreparedConnection,
 } from "../connection/model.ts";
 import * as EnvironmentSupervisor from "../connection/supervisor.ts";
@@ -36,6 +37,7 @@ import * as Persistence from "../platform/persistence.ts";
 import * as RpcSession from "./session.ts";
 import { makeEnvironmentServerConfigState } from "../state/server.ts";
 import { applyServerConfigProjection } from "../state/serverConfigProjection.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 type SocketEventType = "open" | "message" | "close" | "error";
 type SocketEvent = {
@@ -1038,27 +1040,37 @@ describe("RpcSessionFactory", () => {
     ),
   );
 
-  it.effect("fails readiness when the websocket never opens", () =>
-    Effect.gen(function* () {
-      const { factory, sockets } = yield* makeFactory();
-
-      const error = yield* Effect.scoped(
-        Effect.gen(function* () {
-          const session = yield* factory.connect(PREPARED);
-          const readyFiber = yield* Effect.forkChild(Effect.flip(session.ready));
-          yield* awaitSocket(sockets);
+  for (const relay of [false, true]) {
+    it.effect(`fails readiness when the ${relay ? "relay" : "direct"} websocket never opens`, () =>
+      Effect.gen(function* () {
+        const { factory, sockets } = yield* makeFactory();
 
-          yield* TestClock.adjust("15 seconds");
-          return yield* Fiber.join(readyFiber);
-        }),
-      );
+        const error = yield* Effect.scoped(
+          Effect.gen(function* () {
+            const session = yield* factory.connect({
+              ...PREPARED,
+              target: relay
+                ? new RelayConnectionTarget({
+                    environmentId: TARGET.environmentId,
+                    label: TARGET.label,
+                  })
+                : TARGET,
+            });
+            const readyFiber = yield* Effect.forkChild(Effect.flip(session.ready));
+            yield* awaitSocket(sockets);
+
+            yield* TestClock.adjust("15 seconds");
+            return yield* Fiber.join(readyFiber);
+          }),
+        );
 
-      expect(error).toBeInstanceOf(ConnectionTransientError);
-      expect(error).toMatchObject({
-        reason: "transport",
-        message: "Test environment could not establish a WebSocket connection.",
-      });
-      expect(sockets[0]?.readyState).toBe(TestWebSocket.CLOSED);
-    }).pipe(Effect.provide(TestClock.layer())),
-  );
+        expect(error).toBeInstanceOf(ConnectionTransientError);
+        expect(error).toMatchObject({
+          reason: "transport",
+          message: `Test environment could not establish a WebSocket connection.${relay ? ` ${NETWORK_BLOCKING_HINT}` : ""}`,
+        });
+        expect(sockets[0]?.readyState).toBe(TestWebSocket.CLOSED);
+      }).pipe(Effect.provide(TestClock.layer())),
+    );
+  }
 });
diff --git a/packages/client-runtime/src/rpc/session.ts b/packages/client-runtime/src/rpc/session.ts
index 7d975be5c9d3..819f35442e30 100644
--- a/packages/client-runtime/src/rpc/session.ts
+++ b/packages/client-runtime/src/rpc/session.ts
@@ -15,6 +15,7 @@ import * as Option from "effect/Option";
 import * as PubSub from "effect/PubSub";
 import * as Ref from "effect/Ref";
 import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
 import type * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
 import type * as Rpc from "effect/unstable/rpc/Rpc";
@@ -24,6 +25,7 @@ import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
 import * as Socket from "effect/unstable/socket/Socket";
 
 import { makeWsRpcProtocolClient, type WsRpcProtocolClient } from "./protocol.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 import type {
   ConnectionAttemptError,
   ConnectionTransientError,
@@ -107,8 +109,11 @@ function serverConfigReplayEvents(
   return state.themesEvent === undefined ? [snapshot] : [snapshot, state.themesEvent];
 }
 
+const isSocketErrorReason = Schema.is(Socket.SocketErrorReason);
+
 function mapSessionRpcError(
   error: InitialConfigError | ProbeError | ServerConfigSubscriptionError,
+  networkHint: string,
 ): ConnectionAttemptError {
   switch (error._tag) {
     case "EnvironmentAuthorizationError":
@@ -125,7 +130,7 @@ function mapSessionRpcError(
     case "RpcClientError":
       return new ConnectionTransientErrorClass({
         reason: "transport",
-        detail: error.message,
+        detail: `${error.message}${isSocketErrorReason(error.reason) ? networkHint : ""}`,
       });
   }
 }
@@ -138,6 +143,10 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
     options.environmentThemes === true ? { environmentThemes: true } : {};
 
   const connect = Effect.fnUntraced(function* (connection: PreparedConnection) {
+    const networkHint =
+      connection.target._tag === "RelayConnectionTarget" ? ` ${NETWORK_BLOCKING_HINT}` : "";
+    const mapRpcError = (error: Parameters<typeof mapSessionRpcError>[0]) =>
+      mapSessionRpcError(error, networkHint);
     yield* Effect.annotateCurrentSpan({
       "connection.environment.id": connection.environmentId,
     });
@@ -152,9 +161,11 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
             disconnected,
             new ConnectionTransientErrorClass({
               reason: "transport",
-              detail: wasConnected
-                ? `${connection.label} disconnected.`
-                : `${connection.label} could not establish a WebSocket connection.`,
+              detail: `${
+                wasConnected
+                  ? `${connection.label} disconnected.`
+                  : `${connection.label} could not establish a WebSocket connection.`
+              }${networkHint}`,
             }),
           ),
         ),
@@ -244,7 +255,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
         }
         return Effect.all([
           Deferred.failCause(serverConfigExit, exit.cause),
-          Deferred.failCause(configSubscriptionClosed, Cause.map(exit.cause, mapSessionRpcError)),
+          Deferred.failCause(configSubscriptionClosed, Cause.map(exit.cause, mapRpcError)),
         ]).pipe(Effect.asVoid);
       }),
     );
@@ -252,7 +263,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
     const initialConfig = Effect.raceFirst(
       Deferred.await(initialConfigDeferred),
       Deferred.await(serverConfigExit).pipe(
-        Effect.mapError(mapSessionRpcError),
+        Effect.mapError(mapRpcError),
         Effect.flatMap(() => Effect.fail(configSubscriptionEndedError)),
       ),
     ).pipe(Effect.withSpan("environment.initialSync"));
@@ -311,7 +322,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
         (config.environment.capabilities.connectionProbe === true
           ? protocolClient[WS_METHODS.serverProbe]({})
           : protocolClient[WS_METHODS.serverGetConfig]({})
-        ).pipe(Effect.mapError(mapSessionRpcError)),
+        ).pipe(Effect.mapError(mapRpcError)),
       ),
       Effect.asVoid,
       Effect.withSpan("clientRuntime.connection.rpcSession.probe"),

From fba0e088134c8f3988bea93e88b6e172424e21f9 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Fri, 4 Sep 2026 14:30:19 -0700
Subject: [PATCH 3/3] fix(client): preserve descriptor authentication errors

---
 .../src/authorization/service.ts              |  4 +---
 .../src/connection/errors.test.ts             | 20 ++++++++++++++++++-
 .../client-runtime/src/connection/errors.ts   | 19 ++++++------------
 3 files changed, 26 insertions(+), 17 deletions(-)

diff --git a/packages/client-runtime/src/authorization/service.ts b/packages/client-runtime/src/authorization/service.ts
index fa17c288cbeb..d7adc9a99db9 100644
--- a/packages/client-runtime/src/authorization/service.ts
+++ b/packages/client-runtime/src/authorization/service.ts
@@ -83,9 +83,7 @@ const fetchDescriptor = Effect.fn("clientRuntime.connection.remote.fetchDescript
   connectionMethod: ClientConnectionMethod,
 ) {
   return yield* fetchRemoteEnvironmentDescriptor({ httpBaseUrl }).pipe(
-    Effect.mapError(
-      connectionMethod === "relay" ? mapRemoteDpopEnvironmentError : mapRemoteEnvironmentError,
-    ),
+    Effect.mapError((error) => mapRemoteEnvironmentError(error, connectionMethod)),
   );
 });
 
diff --git a/packages/client-runtime/src/connection/errors.test.ts b/packages/client-runtime/src/connection/errors.test.ts
index 0e760bc8f12a..a892ceda7767 100644
--- a/packages/client-runtime/src/connection/errors.test.ts
+++ b/packages/client-runtime/src/connection/errors.test.ts
@@ -5,7 +5,11 @@ import {
 } from "@t3tools/contracts/relay";
 import { describe, expect, it } from "@effect/vitest";
 
-import { mapManagedRelayError, mapRemoteDpopEnvironmentError } from "./errors.ts";
+import {
+  mapManagedRelayError,
+  mapRemoteDpopEnvironmentError,
+  mapRemoteEnvironmentError,
+} from "./errors.ts";
 import { DPOP_RETRY_HINT, DPOP_UNKNOWN_HINT } from "../relay/errorPresentation.ts";
 import { ManagedRelayRequestFailedError } from "../relay/managedRelay.ts";
 import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
@@ -72,6 +76,20 @@ describe("mapManagedRelayError", () => {
 });
 
 describe("mapRemoteDpopEnvironmentError", () => {
+  it("keeps relay descriptor auth failures distinct from DPoP proof failures", () => {
+    const error = new EnvironmentAuthInvalidError({
+      code: "auth_invalid",
+      reason: "invalid_credential",
+      traceId: "trace-descriptor",
+    });
+    expect(mapRemoteEnvironmentError(error, "relay").message).toBe(
+      "The environment credential is invalid.",
+    );
+    expect(mapRemoteDpopEnvironmentError(error).message).toBe(
+      `The environment credential is invalid. ${DPOP_UNKNOWN_HINT}`,
+    );
+  });
+
   it.each([
     new RemoteEnvironmentAuthFetchError({
       message: "Failed to fetch remote environment endpoint.",
diff --git a/packages/client-runtime/src/connection/errors.ts b/packages/client-runtime/src/connection/errors.ts
index b026f1ae89a3..be7a1822cbde 100644
--- a/packages/client-runtime/src/connection/errors.ts
+++ b/packages/client-runtime/src/connection/errors.ts
@@ -1,4 +1,4 @@
-import type { EnvironmentId } from "@t3tools/contracts";
+import type { ClientConnectionMethod, EnvironmentId } from "@t3tools/contracts";
 import type { RelayProtectedError } from "@t3tools/contracts/relay";
 import type { ManagedRelayClientError } from "../relay/managedRelay.ts";
 import { dpopFailureMessage, relayProtectedErrorMessage } from "../relay/errorPresentation.ts";
@@ -114,7 +114,9 @@ export function mapManagedRelayError(error: ManagedRelayClientError): Connection
 
 export function mapRemoteEnvironmentError(
   error: RemoteEnvironmentAuthError,
+  connectionMethod: ClientConnectionMethod = "direct",
 ): ConnectionAttemptError {
+  const networkHint = connectionMethod === "relay" ? ` ${NETWORK_BLOCKING_HINT}` : "";
   switch (error._tag) {
     case "EnvironmentAuthInvalidError":
       return new ConnectionBlockedError({
@@ -147,12 +149,12 @@ export function mapRemoteEnvironmentError(
     case "RemoteEnvironmentAuthTimeoutError":
       return new ConnectionTransientError({
         reason: "timeout",
-        detail: error.message,
+        detail: `${error.message}${networkHint}`,
       });
     case "RemoteEnvironmentAuthFetchError":
       return new ConnectionTransientError({
         reason: "network",
-        detail: error.message,
+        detail: `${error.message}${networkHint}`,
       });
     case "EnvironmentInternalError":
       return new ConnectionTransientError({
@@ -179,15 +181,6 @@ export function mapRemoteEnvironmentError(
 export function mapRemoteDpopEnvironmentError(
   error: RemoteEnvironmentAuthError,
 ): ConnectionAttemptError {
-  if (
-    error._tag === "RemoteEnvironmentAuthFetchError" ||
-    error._tag === "RemoteEnvironmentAuthTimeoutError"
-  ) {
-    return new ConnectionTransientError({
-      reason: error._tag === "RemoteEnvironmentAuthFetchError" ? "network" : "timeout",
-      detail: `${error.message} ${NETWORK_BLOCKING_HINT}`,
-    });
-  }
   if (error._tag === "EnvironmentAuthInvalidError" && error.reason === "invalid_credential") {
     return new ConnectionBlockedError({
       reason: "authentication",
@@ -195,5 +188,5 @@ export function mapRemoteDpopEnvironmentError(
       traceId: error.traceId,
     });
   }
-  return mapRemoteEnvironmentError(error);
+  return mapRemoteEnvironmentError(error, "relay");
 }