🐛 BUG: connect() on remote VPC Network bindings fails in local dev with "Incoming CONNECT on a worker not supported"

[mack-erel]

Which Cloudflare product(s) does this pertain to?

Wrangler, Miniflare (remote bindings)

What versions are you using?

• wrangler 4.110.0 (also reproduced on workers-sdk main @ c7dbe1a)
• miniflare 4.20260708.1 / workerd 1.20260708.1
• node v26.4.0, macOS (darwin arm64)

What operating system and mode are you using?

macOS, wrangler dev (local mode with remote bindings) and getPlatformProxy() (via @sveltejs/adapter-cloudflare)

Describe the Bug

What happened

With a vpc_networks binding configured with remote: true, calling the binding's raw-TCP API from a Worker in local dev fails immediately:

// wrangler.jsonc
{
  "vpc_networks": [
    { "binding": "VPC_NETWORK", "tunnel_id": "<TUNNEL_ID>", "remote": true }
  ]
}

const socket = await env.VPC_NETWORK.connect("db-host:3306"); // throws

• wrangler dev: TypeError: Incoming CONNECT on a worker not supported (thrown synchronously from connect())
• getPlatformProxy() (vite dev): surfaces as TypeError: This ReadableStream is disturbed (has already been read from), and cannot be used as a body., with the underlying workerd log showing the same root error:
  workerd/api/sockets.c++:449: error: Socket proxy disconnected abruptly; e = workerd/io/worker-entrypoint.c++:648: failed: jsg.TypeError: Incoming CONNECT on a worker not supported

fetch() on the same binding relays correctly in both modes. The same connect() call works when the Worker is deployed (TCP connect() over VPC Networks, GA 2026-06-16).

Root cause (traced to source)

Remote bindings are wired locally as a JS proxy worker, and that worker cannot receive the native CONNECT that Fetcher#connect() produces:

1. Miniflare registers every remote-capable binding (including vpc_networks) as a workerd Service.worker running packages/miniflare/src/workers/shared/remote-proxy-client.worker.ts, which implements fetch() and capnweb JSRPC relay only — there is no connect handler (packages/miniflare/src/plugins/vpc-networks/index.ts → remoteProxyClientWorker() in packages/miniflare/src/plugins/shared/constants.ts).
2. env.BINDING.connect(addr) is a native (C++) code path: workerd turns it into an HTTP CONNECT delivered to that proxy worker's entrypoint.
3. WorkerEntrypoint::connect rejects inbound CONNECT unless the receiving worker has the connect_pass_through or experimental compat flag (workerd/src/workerd/io/worker-entrypoint.c++:648). The proxy client worker has neither, so the call dies locally — the request never reaches the remote proxy session.
4. The edge side (packages/wrangler/templates/remoteBindings/ProxyServerWorker.ts) also only handles fetch/JSRPC; there is no socket relay path.

Note the existing remote-bindings e2e test for VPC Networks only exercises .fetch() (and is currently skipped), so this raw-TCP gap has no coverage.

Feasibility evidence (we prototyped each building block)

We ran three spikes on main to check a fix is viable without any workerd changes:

1. Local ingress works. A miniflare worker with compatibilityFlags: ["experimental"] and an export default { connect(socket) } handler (workerd's inbound connect handler, merged in EW-9330 Implement connect() handler workerd#6059) successfully receives a service-binding connect() from another worker, with bidirectional bytes. Without the per-worker flag it fails with exactly the error above (the global --experimental CLI flag miniflare already passes is not sufficient — the check is per-worker).
2. The target address is recoverable. The caller's connect("host:port") authority arrives verbatim as (await socket.opened).localAddress in the handler (matching the contract exercised by workerd/src/workerd/api/tests/connect-handler-test.js), so no extra address-negotiation protocol is needed.
3. The edge side already works. We added a temporary diagnostic branch to ProxyServerWorker.ts that calls env[binding].connect(addr) inside a real remote proxy session (started via startRemoteProxySession() with a real vpc_network binding + Cloudflare Tunnel): the connect succeeded and returned the first 78 bytes of a genuine MySQL handshake from a private-network database. So connect() on the raw binding is fully functional in the preview session context.

Proposed fix (we're happy to submit a PR)

• remote-proxy-client.worker.ts: add a connect(socket) handler; recover the target address from socket.opened.localAddress; relay the byte stream to the remote proxy session over a WebSocket (binary frames), following the auth/headers conventions of the existing fetch/JSRPC relay.
• ProxyServerWorker.ts: add a WebSocket tunnel endpoint that calls await env[binding].connect(address) and pipes both directions, propagating close/error.
• plugins/shared/constants.ts / plugins/vpc-networks: opt the proxy client worker into the experimental compat flag (scoped to bindings that need raw TCP), since the inbound connect handler is still experimental-gated in workerd.

Open questions we'd like maintainer input on before sending the PR:

• Is enabling the experimental compat flag on miniflare's internal proxy-client worker acceptable, given the inbound connect handler (workerd#6059) is not yet stable? If not, would you prefer this gated behind an --experimental-* wrangler flag per the naming conventions in CONTRIBUTING.md?
• Should the relay reuse the existing capnweb WebSocket session or open a dedicated WebSocket per socket? (Our prototype assumes a dedicated WS per connect() for simplicity.)

Reproduction

Minimal repro:

// wrangler.jsonc
{
  "name": "vpc-connect-repro",
  "main": "src/index.ts",
  "compatibility_date": "2026-07-15",
  "vpc_networks": [{ "binding": "VPC_NETWORK", "tunnel_id": "<TUNNEL_ID>", "remote": true }]
}

// src/index.ts
export default {
  async fetch(_req: Request, env: { VPC_NETWORK: Fetcher }) {
    try {
      const socket = await (env.VPC_NETWORK as any).connect("<PRIVATE_HOST>:3306");
      const { value } = await socket.readable.getReader().read();
      return Response.json({ ok: true, bytes: value?.length });
    } catch (e) {
      return Response.json({ ok: false, error: String(e) }, { status: 500 });
    }
  }
};

wrangler dev → curl → {"ok":false,"error":"TypeError: Incoming CONNECT on a worker not supported"}.
The same Worker deployed → {"ok":true,"bytes":78} (MySQL greeting via Cloudflare Tunnel).

Please provide a link to a minimal reproduction

The snippets above are the minimal reproduction. A self-contained repro repository is not practical here because reproducing requires an account-specific Cloudflare Tunnel and a private database behind it.

Please provide any relevant log output

✘ [ERROR] workerd/server/server.c++:...: error: Uncaught: workerd/io/worker-entrypoint.c++:648: failed: jsg.TypeError: Incoming CONNECT on a worker not supported
workerd/api/sockets.c++:449: error: Socket proxy disconnected abruptly

[workers-devprod]

Note

This is an automated, advisory triage report generated by workers-devprod. It is not an official maintainer response — a maintainer will follow up.

🤖 Automated triage report

Issue Triage: #14710

Summary

connect() (raw TCP) on a remote: true VPC Network binding fails in local dev (wrangler dev / getPlatformProxy()) with TypeError: Incoming CONNECT on a worker not supported, because miniflare's remote-proxy-client worker only relays fetch()/JSRPC and has no connect handler.

Classification

• Type: Bug
• Component: packages/miniflare (remote-bindings proxy worker) + packages/wrangler (remote-binding proxy server template)
• Severity: Medium
• Has Reproduction: Yes (inline minimal repro; no clonable repo, justified — requires an account-specific Cloudflare Tunnel + private DB)
• Quality: Complete

Findings

• Created: 2026-07-16T03:43:08Z
• Author: mack-erel
• Version: wrangler 4.110.0 (also reproduced on main @ c7dbe1a); miniflare 4.20260708.1 / workerd 1.20260708.1; node v26.4.0; macOS arm64
• Labels: none
• Comments: 0

Analysis

• Clear, well-scoped bug with a source-traced root cause. The reporter identifies that remote bindings are served locally by a JS proxy worker (remote-proxy-client.worker.ts) that implements only fetch() + capnweb JSRPC relay and has no connect handler, so a native inbound CONNECT (produced by Fetcher#connect()) is rejected at WorkerEntrypoint::connect unless the worker has the connect_pass_through/experimental compat flag.
• Consistent across two entry points. Manifests as Incoming CONNECT on a worker not supported under wrangler dev, and surfaces indirectly as a "ReadableStream is disturbed" error under getPlatformProxy()/vite, but the underlying workerd log confirms the same root error. fetch() on the same binding works locally, and connect() works when deployed — isolating the gap to local dev remote-binding plumbing.
• Feasibility already prototyped. The reporter ran three spikes on main showing a fix needs no workerd changes: (1) local inbound connect works with a per-worker experimental flag; (2) the target address is recoverable via socket.opened.localAddress; (3) the edge ProxyServerWorker can call env[binding].connect(addr) inside a real remote proxy session (returned a real 78-byte MySQL handshake).
• Concrete fix proposed, PR offered. Add a connect(socket) handler to remote-proxy-client.worker.ts, a WebSocket tunnel endpoint in ProxyServerWorker.ts, and opt the proxy client worker into the experimental compat flag. Reporter raises two design questions (experimental flag vs. a scoped --experimental-* wrangler flag; reuse capnweb WS vs. a dedicated WS per socket) that need maintainer input before a PR.
• No test coverage today. Reporter notes the existing VPC Networks remote-bindings e2e only exercises .fetch() and is currently skipped, so this raw-TCP path is untested.
• Note: the specific source paths cited could not be verified in this checkout (the packages/ tree is not present here), but they are consistent with the documented miniflare/wrangler architecture. Maintainer should confirm the exact current file locations.

Recommendation

Status: KEEP OPEN

Reasoning: This is a legitimate, reproducible functional gap in local dev for remote VPC Network bindings, backed by a source-level root-cause analysis and working prototype evidence. It is not closeable under any Step 2 category and has enough detail to act on; it primarily needs a maintainer decision on the two design questions before the offered PR can land.

Action: Route to the miniflare / remote-bindings owner to (1) confirm the current file locations and the connect-handler gap, and (2) answer the reporter's two design questions (experimental compat flag on the internal proxy-client worker vs. a scoped --experimental-* gate; single shared capnweb WS vs. dedicated WS per connect()). Given the reporter has offered a PR, respond with the preferred approach so they can proceed, and add e2e coverage for the raw-TCP path (currently only .fetch() is tested and skipped).

Suggested Labels: none (applying labels omitted — cannot confirm exact label names like miniflare/bug exist in the repo from the available data)

Suggested Comment

Thanks for the exceptionally detailed report and root-cause analysis — the breakdown of the proxy-client connect-handler gap and the three feasibility spikes are really helpful. This looks like a genuine gap in how remote bindings are proxied in local dev: the remote-proxy-client worker only relays fetch()/JSRPC, so native inbound CONNECT from Fetcher#connect() is rejected.

Before you open a PR, we'd like to align on your two open questions:

1. Whether enabling the experimental compat flag on miniflare's internal proxy-client worker is acceptable, or whether we'd prefer to gate this behind a scoped --experimental-* wrangler flag.
2. Whether the relay should reuse the existing capnweb WebSocket session or open a dedicated WebSocket per socket.

A maintainer will follow up with a preferred direction. If you do send a PR, please also add e2e coverage for the raw-TCP (connect()) path — the existing VPC Networks remote-bindings test only exercises .fetch() and is currently skipped.

Structured summary (JSON)

{
  "issueNumber": 14710,
  "title": "connect() on remote VPC Network bindings fails in local dev with \"Incoming CONNECT on a worker not supported\"",
  "githubUrl": "https://github.com/cloudflare/workers-sdk/issues/14710",
  "recommendation": "KEEP OPEN",
  "difficulty": "medium",
  "reasoning": "Legitimate, reproducible local-dev gap: the miniflare remote-proxy-client worker relays only fetch/JSRPC and has no connect handler, so raw-TCP connect() on remote VPC Network bindings is rejected. Root cause is source-traced and a fix is prototyped, but two design questions need maintainer input.",
  "suggestedAction": "Route to the miniflare/remote-bindings owner to confirm the current file locations and answer the reporter's two design questions (experimental compat flag vs. a scoped --experimental-* gate; shared capnweb WS vs. dedicated WS per connect), then unblock the offered PR and add e2e coverage for the raw-TCP path.",
  "hasSuggestedComment": true,
  "suggestedLabels": []
}