[miniflare] Remote Hyperdrive bindings log "your Worker's code had hung" on every connection

[mack-erel]

What versions & operating system are you using?

Wrangler 4.125.0 (built from main plus #14900), Node v26.4.0, macOS 26.5.2.

Please provide a link to a minimal reproduction

No public repository — the reproduction needs a real Hyperdrive configuration on the account. The Worker and configuration are small enough to inline; see below.

Describe the Bug

Every connection made through a remote Hyperdrive binding in wrangler dev causes the runtime to log:

✘ [ERROR] Error: The Workers runtime canceled this request because it detected that
your Worker's code had hung and would never generate a response.

Queries are unaffected — responses are correct and return in 0.1–0.35s — but the message appears once per connection, so ordinary use produces a steady stream of alarming errors. This surfaced while testing remote Hyperdrive bindings (#14900); the relay it happens in predates that work.

Reproduction. A Worker with two remote: true Hyperdrive bindings and no localConnectionString:

{
	"compatibility_flags": ["nodejs_compat"],
	"hyperdrive": [
		{ "binding": "HYPERDRIVE_PG", "id": "<postgres-config-id>", "remote": true },
		{ "binding": "HYPERDRIVE_MYSQL", "id": "<mysql-config-id>", "remote": true }
	]
}

The Worker runs SELECT version() through postgres and SELECT VERSION() through mysql2, then closes both connections. Under wrangler dev, 10 such requests (20 connections) produced 16 of these errors while every response was a correct 200.

What is established.

• One error per remote Hyperdrive connection, at the same rate for the Postgres and the MySQL binding, so it is not driver-specific.
• It correlates 1:1 with the bridge's WebSocket closing abnormally. Instrumenting HyperdriveProxyController.#handleRemoteBridgeConnection over 5 requests gave 11 opens: 4 closed cleanly (code 1000) and 7 closed abnormally (code 1006), against exactly 7 of these errors. Connections that close cleanly never produce one.
• It does not originate in the user's Worker — every span reported by the local observability API is ok. Requests that do not touch the database produce no errors at all.

Hypotheses measured and disproven, recorded so nobody repeats them:

1. A pre-existing fault in the shared handleConnect relay in ProxyServerWorker. A VPC-network connect() binding driving that same relay logged zero errors across every variation tried.
2. Long-lived connections. VPC connections held open for 3s and for 20s still logged zero.
3. Connections the client never closes. Abandoning the VPC socket entirely still logged zero.
4. The relay being a floating promise. Registering it with ctx.waitUntil in handleConnect measured 1.60 errors per request against a 1.67 baseline over 10 requests — no effect.

The remaining difference between the two paths is the client side. Hyperdrive drives the relay from the Node ws bridge in packages/miniflare/src/plugins/hyperdrive/hyperdrive-proxy.ts, whereas a VPC network binding uses workerd's own fetch-upgrade in packages/miniflare/src/workers/shared/remote-proxy-client.worker.ts. Both reach the same handleConnect in packages/remote-bindings/templates/remoteBindings/ProxyServerWorker.ts.

Please provide any relevant error logs

Bridge WebSocket lifecycle for a connection that does not produce the error:

[HD-BRIDGE] ws open
[HD-BRIDGE] clientSocket close (ws state 1)
[HD-BRIDGE] ws close code=1000

And for one that does — the close arrives as an abnormal closure, with the runtime error alongside it:

[HD-BRIDGE] ws open
[HD-BRIDGE] ws close code=1006
✘ [ERROR] Error: The Workers runtime canceled this request because it detected that
your Worker's code had hung and would never generate a response.

[workers-devprod]

Automated triage

✅ Issue triage completed.

• Reproduction: ⚠️ Blocked.
• Actionability: ✅ Actionable.
• Type: Bug (high confidence).
• Labels:
  • package:miniflare (high)
  • product:hyperdrive (high)
  • feature:remote-bindings (medium)

Reproduction details

The reported behavior requires remote Hyperdrive bindings introduced in PR #14900, which is not present in the cloned repository (hyperdrive is currently local-only). It also requires a real Cloudflare Hyperdrive configuration and account credentials, neither of which are available in the sandbox.

Artifact: Download reproduction archive (Cloudflare Access required).

Treat archive contents as untrusted. Inspect them before running anything.

Actionability and missing information

Detailed report: remote Hyperdrive bindings in wrangler dev log a runtime hung-request error per connection while queries succeed. Includes versions, inline config, steps, expected/actual behavior, bridge logs, and relevant miniflare/remote-bindings source paths.

[mack-erel]

Fixed in #14900 (8fc67128).

Cause. A database client disconnects at the protocol level — Postgres Terminate, MySQL COM_QUIT — before dropping its TCP connection. That message has already been relayed by the time the bridge's client socket closes, so the edge closes the tunnel itself about 10ms later. The bridge was closing the WebSocket as soon as its client socket went away, which raced that: when the bridge won, the runtime severed the edge relay mid-flight and reported it as a request that hung.

That also explains the 1:1 correlation with close code 1006 in the report above. The abnormal closure was not the trigger — both were symptoms of the same severed relay.

The decisive measurement was removing the bridge's ws.close() entirely, over 5 requests:

	hung reports	close 1000	close 1006
before	7	3	7
without the bridge's ws.close()	0	10	0

Fix. The bridge now waits for the edge to close the tunnel and forces it down only if the edge does not, which is what happens when a client dies without disconnecting cleanly. The forced path terminates the socket rather than closing it gracefully: a close handshake needs the relay to run code it can no longer run, and produces the same report — measured at 6 reports over 3 requests with a graceful close there, and none with a terminate.

Verification. Against real Postgres and MySQL Hyperdrive configurations, 30 connections across both clean and abandoned disconnects: previously about one report per connection, now none, with query results unchanged.

One note for anyone hitting something similar: this was reported against the shared handleConnect relay, but the relay was not at fault. A VPC-network connect() binding driving the same relay never produced a report, under every variation tried. The fault was in how the Hyperdrive bridge closed its end.