ERR_HTTP2_INVALID_SESSION poisons the process until restart — forcing HTTP/1.1 (undici allowH2:false) restores recoverability (measured)

[zhangmq]

TL;DR

After a single TLS-layer failure, every subsequent model request failed in 1–2 ms with
ERR_HTTP2_INVALID_SESSION ("The session has been destroyed") and never recovered — only restarting
dsh fixed it. Forcing the process to HTTP/1.1 (undici global dispatcher with allowH2: false)
restores recoverability: the underlying connection errors still happen, but each one is now an
ordinary retryable request failure that recovers within the same turn — no restart, and zero
ERR_HTTP2_INVALID_SESSION since.

Measured before/after (same machine, same route, same provider):

	before	after (~1.1 h observation)
ERR_HTTP2_INVALID_SESSION	24 (continuous, 4 min)	0
failure shape	1–2 ms, no DNS/TCP egress (reusing a dead h2 session)	~0.9–1.2 s — connection is really established, then closed by the peer (UND_ERR_SOCKET: other side closed)
recoverable?	❌ no — retries hit the same poisoned session; restart required	✅ yes — retry #1/#2 recovers inside the same turn
turns	session paralyzed	4/4 completed, no restart

Symptom and evidence

Captured at the fetch layer (error.cause chains), DeepSeek Harness 0.1.5-rc.2, Node v26.8.2:

15:25:06  POST https://opencode.ai/zen/go/v1/chat/completions
          TypeError: fetch failed
            └─ ... SSL routines:ssl3_read_bytes:ssl/tls alert bad record mac
          code = ERR_SSL_SSL/TLS_ALERT_BAD_RECORD_MAC        <- trigger

15:25:07 → 15:29:30   (24 consecutive requests)
          TypeError: fetch failed
            └─ The session has been destroyed
          code = ERR_HTTP2_INVALID_SESSION   elapsed = 1–2 ms

While poisoned, the local tunnel logged no DNS query and no TCP connection for those requests —
i.e. the failures were entirely local, consistent with re-use of a destroyed HTTP/2 session rather
than a reconnect. Retries could not help, and raising retryPolicy.maxRetries only changed how long
each turn waited before dying.

Mechanism

undici enables HTTP/2 by default — allowH2 = allowH2 != null ? allowH2 : true
(undici/lib/core/connect.js), ALPN ['http/1.1','h2']. Against an h2-capable edge an HTTP/2 session
is negotiated; once that session is destroyed (here by a TLS record failure on the wire), the client
keeps re-using it instead of reconnecting, so every later request fails locally.

Note the installed undici is 8.10.2, which already contains nodejs/undici#5310 ("reset invalid
HTTP/2 sessions") and #5453 ("requeue request on GOAWAY'd session") — lib/dispatcher/client-h2.js
has the ERR_HTTP2_INVALID_SESSION → resetHttp2Session() + requeueUnsentRequest() path — yet the
session stayed poisoned for 4 minutes here. A standalone reproduction was not achieved: three
self-contained attempts (graceful h2 session destroy, socket destroy between requests, socket destroy
mid-stream) all reconnected correctly on the next request in undici 8.10.2. The production failure
needs the TLS-layer failure to occur on a live h2 connection.

Mitigation (verified)

Install a global dispatcher that never negotiates h2:

const { Agent, setGlobalDispatcher } = await import('undici')
setGlobalDispatcher(new Agent({ allowH2: false }))

Verification that it takes effect (the same process also uses Node's built-in fetch, whose
dispatcher is shared through the undici global symbol):

dispatcher	measured ALPN
default Agent	HTTP 200 ALPN=["h2"]
new Agent({ allowH2: false })	HTTP 200 ALPN=["http/1.1"]

HTTP/1.1 has no session-level state: a broken connection is an ordinary socket error and the next
request opens a fresh connection. We run this as a small local plugin that installs the dispatcher
after dsh-http-proxy does, with a guard that skips overriding when a proxy dispatcher is already
installed (so HTTPS_PROXY setups are not broken), and logs the before/after dispatcher on every
boot for verification.

What this does not claim

• The underlying connection closures are not fixed. After the mitigation the same endpoint still
  saw 18 UND_ERR_SOCKET: other side closed events in ~1.1 h (17 of them at ~1 s elapsed: connect +
  TLS, then closed by the peer; one at 17.9 s). Who closes them — the gateway, an intermediary, or the
  local tunnel — is not determined; no speculation here.
• The observation window is short (~1.1 h of real use at the time of writing; continuing).
  The claim is narrow and falsifiable: if a poisoned h2 session returns, ERR_HTTP2_INVALID_SESSION
  will reappear here. So far it has not.
• The original criterion for "fixed" was recoverability, not error-freeness: transient path errors
  are expected on this route; what must never happen again is a session that can only be recovered by
  restarting the process.

Suggestion for the harness

In @deepseek-ai/dsh-http-proxy's direct (no-proxy) path, install the agent as
new undici.Agent({ allowH2: false }), or reset the dispatcher/connection when a TRANSPORT failure
carries ERR_HTTP2_INVALID_SESSION. That converts a "process is dead until restart" failure into a
single retryable request error — which is what we measured after applying it locally.

Related

• fix: reset invalid HTTP/2 sessions nodejs/undici#5310 (merged) and DSH | dsh-vision-autoswitch | 有图自动切Vision，无图回落到Pro/Flash Image in → Vision, image out → back to Pro/Flash #5453 — HTTP/2 resilience fixes already present in 8.10.2.
• [ERR_HTTP2_INVALID_SESSION]: The session has been destroyed — causes repeated transient retries github/copilot-cli#3304 — same symptom in another long-running CLI, still open.
• fix(http): remove allowH2 from undici Agent — causes fetch failed on Node.js 22+ openclaw/clawhub#245 (merged) — same class, fixed by removing allowH2.
• Pi crashes on uncaught ERR_HTTP2_INVALID_SESSION from undici HTTP/2 transport earendil-works/pi#4682 — the same error surfacing in another transport; auto-closed.

[PerryLink]

Your mechanism holds up against HEAD (ddefc45fbc, v0.1.6-alpha.2), with two source-grounded refinements.

The harness never passes allowH2 anywhere — I grepped all packages, zero matches. packages/util/http-proxy/src/install.ts:143-157 builds the policy dispatcher as new Agent({ factory(origin, options) { ... } }), and the direct-over-installed branch at :196 uses new undici.Agent() — both inherit undici's default. The pinned undici is ^8.10.0 (packages/util/http-proxy/package.json:33, locked at 8.10.0 in pnpm-lock.yaml), and I verified upstream that 8.10.0's connector defaults to HTTP/2: lib/core/connect.js has allowH2 = allowH2 != null ? allowH2 : true with ALPN ['http/1.1','h2']. So whenever the harness installs a dispatcher, it can negotiate h2.

Two refinements to the suggestion:

1. The no-proxy path installs nothing today. installGlobalProxy with policy.source === 'none' and nothing previously installed just records the policy and returns (install.ts:176-187). So forcing HTTP/1.1 for direct deployments requires the launcher to also install a direct Agent({ allowH2: false }) in the 'none' branch — your suggestion implies that extra step, which is a maintainer-side change in install.ts.

2. Your plugin mitigation works, with the proxy caveat you already handled. Model requests are plain fetch() with no dispatcher option (packages/llm/llm-deepseek/src/protocols/messages/adapter.ts:122, .../chat-completions/adapter.ts:330), so they resolve the global dispatcher — replacing it with allowH2: false takes effect. But with HTTPS_PROXY set, the launcher's policy dispatcher does the proxying; overriding the global dispatcher would send those plain-fetch LLM calls direct and unproxied (the web-fetch path is safe because it uses proxyRouteFor's dispatcher explicitly, packages/web/web-fetch-http/src/provider.ts:134-136). Your guard against overriding when a proxy dispatcher is installed is therefore necessary, not optional.

Patchability today: none via config. dsh-http-proxy is explicitly "a library, not a plugin: transport policy has one answer per process, so there is nothing for a composition to mount, swap, or scope" (packages/util/http-proxy/src/index.ts:9-10), and it declares no cordis patch schema — so there is no cordis.patch.yml knob for allowH2; the in-repo fix is an install.ts change (maintainer territory). Your local plugin is the only user-side route I can confirm.

Not verified: why the poisoned session persisted 4 minutes despite the 8.10.x reset paths (you couldn't reproduce standalone either), and your before/after tables — those are your measurements.

If you capture a poisoned run with NODE_DEBUG=http (or undici's debug output), it'd show whether the session was actually reset and re-poisoned, which would complete the picture.