T3 Connect: let users force the managed cloudflared to HTTP/2 — on QUIC-blocking corporate networks the tunnel stays down because cloudflared won't fall back #16344

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

Summary

On networks that drop QUIC (UDP 7844) but allow TCP 7844, T3 Connect goes down for long periods. The managed cloudflared keeps dialing QUIC instead of using HTTP/2, which works on the same networks. This is common on corporate networks: full-tunnel VPNs that fall back from IPsec to an SSL/TLS (TCP 443) tunnel often stop passing QUIC, and some office and tethered networks behave the same way.

T3 always spawns cloudflared tunnel --no-autoupdate --loglevel info --output default run with the default --protocol auto, and it offers no way to choose the transport. A user who knows the network blocks QUIC can't do anything about it. A watchdog that restarts cloudflared (as proposed in #16258) helps less than you'd expect here, for the reasons below.

Why cloudflared doesn't recover on its own (cloudflared 2026.5.2)

1. Fallback is permanently suppressed once QUIC has ever connected. In supervisor/tunnel.go, Serve() returns before choosing a fallback when e.tracker.HasConnectedWith(e.config.ProtocolSelector.Current()) is true. In tunnelstate/conntracker.go, HasConnectedWith only checks ci.Protocol == protocol and ignores IsConnected. Disconnect events only set IsConnected = false, so the protocol record stays. A connector that used QUIC once, for example at home, never falls back to HTTP/2 after the laptop moves to a QUIC-blocking network. It sits at readyConnections: 0 until it is restarted.
2. Even a fresh process falls back slowly. For EdgeQuicDialError, IpAddrFallback.ShouldGetNewAddress only reports a fallback-worthy connectivity error after maxRetries edge-address rotations per connection, and the backoff between attempts grows exponentially. In our logs the retry gaps grew from about 20 s to 2 min to 4.5 min. A fresh connector that had never connected over QUIC took about 18 minutes to fall back.
3. The fallback doesn't stick. One long-lived connector registered over http2 at startup, then registered over quic again on a later reconnect within the same process. It then hit (1) on the next QUIC-blocking network.

So restarting cloudflared resets (1), but on a QUIC-blocking network the new process still starts with QUIC and needs many minutes to fall back.

Steps to reproduce

1. On a network where QUIC works, start the desktop app with T3 Connect on. Confirm a phone can connect. cloudflared registers 4 connections with protocol=quic.
2. Move the host to a network that drops UDP 7844 but allows TCP 7844. In our case this was a corporate full-tunnel VPN running in SSL/TLS fallback mode, on both office Wi-Fi and a phone hotspot.
3. Observe curl -s http://127.0.0.1:<metrics-port>/ready. It returns {"status":503,"readyConnections":0,...} and stays there. The log shows repeated failed to dial to edge with quic: timeout: no recent network activity or handshake did not complete in time.
4. Try to connect from the phone. It shows Remote environment endpoint https://<relay-host>/oauth/token timed out after 10000ms or a similar error.

Expected behavior

• A setting to choose the managed connector's transport: auto (default), http2, or quic, passed to cloudflared as --protocol. An equivalent flag or env var for t3 serve would also help headless hosts.
• Optionally, if the connector can't register over QUIC for a while, T3 could respawn it with --protocol http2. This would fit the watchdog proposed in [Bug]: T3 Connect stays down after a network change: cloudflared keeps running with zero connections and is never restarted #16258. A restart that keeps auto may not help on these networks.

Actual behavior

What we measured on the same host (macOS, Apple silicon):

• QUIC was checked with a raw QUIC version-negotiation probe (reserved version 0x0a0a0a0a). TCP 7844 was checked with nc -z.
• On the blocked path, the connector's metrics showed quic_client_total_connections climbing (45 → 115) with quic_client_latest_rtt 0 and no received bytes.
• After forcing HTTP/2 (see Workaround), the connector registered 4 connections with protocol=http2 within a minute on the same office network. /.well-known/t3/environment through the relay hostname answered 200 in about 0.1 s.

Impact

Major degradation or frequent failure

Version or commit

Desktop 0.0.46-nightly.20261005.2702 (macOS "T3 Code (Nightly)")

Environment

macOS 26.6.2 (Apple silicon), managed cloudflared 2026.5.2, iOS app (build 105), corporate full-tunnel VPN with IPsec → SSL/TLS fallback

Logs or stack traces

ERR Failed to dial a quic connection error="failed to dial to edge with quic: timeout: no recent network activity" connIndex=0 event=0 ip=198.41.200.113
WRN Failed to dial a quic connection error="failed to dial to edge with quic: timeout: handshake did not complete in time" connIndex=0 event=0 ip=198.41.200.113
# /ready on the stuck connector:
{"status":503,"readyConnections":0,"connectorId":"<redacted>"}
# after forcing http2, same network:
INF Registered tunnel connection connIndex=0 ... location=<redacted> protocol=http2

Workaround

T3 spawns cloudflared with env: { ...process.env, TUNNEL_TOKEN }, so cloudflared's own env var for --protocol is inherited:

launchctl setenv TUNNEL_TRANSPORT_PROTOCOL http2
# then quit T3 Code and relaunch it from the Dock or Finder

This is undocumented, applies to every app launched afterwards, and is lost on reboot or logout. Turning the VPN off also works, but that's often not an option on a work machine.

Related

• [Bug]: T3 Connect stays down after a network change: cloudflared keeps running with zero connections and is never restarted #16258: a connector stuck at zero connections is never restarted. The proposed watchdog would help with (1) above, but not with (2) or (3) unless it can switch to HTTP/2.
• T3 Connect: new connections fail after the host joins a VPN because the managed cloudflared keeps a stale QUIC MTU #15897: stale QUIC MTU after joining a VPN. It lists "let users force --protocol http2" as one possible direction.
• [Bug]: T3 Connect treats a spawned but unreachable tunnel as 'running' #7447: a connector is reported as running before it registers.