Repository navigation
[Bug]: T3 Connect silently never starts when cloudflared is missing from the managed folder and the app's PATH (macOS) #15918
Description
Before submitting
- I searched existing issues and did not find a duplicate.
- I included enough detail to reproduce or investigate the problem.
Area
apps/server
Steps to reproduce
- macOS, T3 Code Alpha launched from the Dock/Finder, T3 Connect linked and enabled.
- Make sure
~/.t3/tools/cloudflared/<pinned version>/darwin-arm64/cloudflareddoes not exist. In my case Homebrew hadcloudflared2026.2.0 in/opt/homebrew/bin. - Check the server's PATH:
ps eww -p <server pid>showsPATH=/usr/bin:/bin:/usr/sbin:/sbin, so the Homebrew copy is not found. - Open the environment from the iOS app.
Expected behavior
The app tells the user the relay client is missing and offers to install it, and the phone says something more useful than a generic connection failure. The server already knows what is wrong: the runtime status is failed with failure: "not-installed".
Actual behavior
server.trace.ndjsonshowsenvironment.cloud.activateManagedTunnelfailing repeatedly withEnvironmentCloudEndpointUnavailableError: Managed endpoint runtime could not be started.not-installedis classed as retryable, so the server keeps retrying (exponential backoff capped at 30s) and nothing installs the binary.- In the settings screen I was looking at, T3 Connect showed as enabled with no relay-client warning. I know there is a "Relay client: not installed" string and
cloudGetRelayClientStatus/cloudInstallRelayClientRPCs, so this may be surfaced somewhere I did not look, but nothing prompted me when the tunnel failed. - The phone only shows:
Failed to connect. Reconnecting… Reason: Relay could not reach the environment endpoint (endpoint_request_failed). Trace ID: 0651e6fccb18ee2ee27f9dc6d09804ba. - Placing the checksum-verified pinned release (2026.5.2,
cloudflared-darwin-arm64.tgz) in the managed folder fixed it within seconds, with no restart. The tunnel then registered 4 connections.
The pinned version is part of the managed folder path, so a release that bumps the pin would make an existing managed copy invisible. I did not confirm that this is what happened here.
Related, but different causes: #7447 (status reports running for a tunnel that never registered; also a generic phone error) and #13964 (cloudflared found on PATH without a version check).
Impact
Major degradation or frequent failure
Version or commit
Desktop Alpha 0.0.45
Environment
macOS (Darwin 25.6.0), Apple Silicon, iOS client
Activity
juliusmarminge commentedon Oct 5, 2026
Note
Grok responding on behalf of Julius.
Triage
Thanks @kevvykevwin for the detailed report, especially the
PATHfrom the Dock-launched server and the check that placing the2026.5.2build fixed it without a restart. That made this easy to trace.What I found
cloudflared2026.5.2.RelayClient.resolvechecks an override, then~/.t3/tools/cloudflared/2026.5.2/<platform>-<arch>/cloudflared, thencloudflaredonPATH. With aPATHof only/usr/bin:/bin:/usr/sbin:/sbin, Homebrew's copy isn't visible, so the status comes backmissing, which the runtime maps tofailure: "not-installed".not-installedas retryable and callsactivateManagedTunnelagain on a backoff capped at 30 seconds. Nothing in that loop downloads the binary. Each retry re-checks the managed path, which is why dropping the binary in worked without a restart.ensureRelayClientAvailable) only runs while linking or toggling the managed-tunnel switch. The settings row doesn't check relay-client status, and its switch reflects the stored runtime config (managedTunnelActive), so T3 Connect can read as available while the connector is down.Relay client: not installedcomes fromt3 connect status.endpoint_request_failedis the generic message for a failed endpoint mint when the relay can't reach the host, so it doesn't point at the missing binary.Related but different: #13964 / #13968 (a
PATHbinary used with no version check), #11184 (pin bump, which would also make an older managed copy invisible), #7447 (spawned process reported as running before the tunnel registers), #14836 (Windows ARM64 with no managed asset), and #15897 (stale QUIC MTU after a VPN change).Likely fix area
Options include surfacing
not-installedon the T3 Connect row inConnectionsSettingsand offering the existing install flow there, having an already-linked host run that install path instead of retrying activation indefinitely (activateManagedTunnelWithRetryinapps/server/src/cloud/http.ts), and giving the mobile error a more specific message when the host is missing the relay client. It may also be worth settling this before #11184 changes the versioned managed path.A maintainer will decide on the fix direction.