wrangler dev remote: cloudflared tunnel failed to establish

TL;DR

wrangler dev --remote opens a cloudflared tunnel from your machine to Cloudflare so the remote runtime can reach your session, and the whole command dies if that tunnel cannot establish. Re-run with debug logging to see where it breaks, make sure the cloudflared binary is present and can make outbound connections, and if the network simply will not allow tunnels, drop back to plain local wrangler dev.

Failed to establish tunnel connection

Steps

1. Re-run with debug logging to see the actual failure point:

wrangler dev --remote --log-level debug

Expected: the log shows whether it failed downloading cloudflared, connecting, or authenticating the tunnel. That line decides the next step.

2. Check the cloudflared binary wrangler relies on:

cloudflared --version

Expected: a version string. If the command is not found, wrangler tries to fetch it on first use; a blocked download is itself the failure, so install cloudflared manually and put it on your PATH.

3. Check the network path. The tunnel is outbound-only from your machine, but corporate proxies and firewalls sometimes block the tunnel protocol. Try from an unrestricted network, or have the network team allow outbound tunnel traffic to Cloudflare.

Expected: on a clear network the tunnel establishes and remote dev starts.

4. If tunnels are not permitted in your environment, use local mode instead:

wrangler dev

Expected: the worker runs locally without any tunnel. You lose remote-only fidelity, but development unblocks.

Use this when

• wrangler dev --remote fails with a cloudflared tunnel error
• Remote dev worked on one network and fails on another
• The failure mentions the tunnel, not bindings or code

Not for this skill when

• Plain wrangler dev (no --remote) fails; there is no tunnel involved there
• The tunnel connects but the worker errors on bindings or code
• You are debugging a deployed worker, not a dev session

Variant phrasings

• wrangler dev remote tunnel failed to connect
• cloudflared tunnel error wrangler dev
• wrangler remote dev mode cannot establish connection

Why it happens

Remote mode keeps your code on your machine while the worker executes against real Cloudflare resources, and the tunnel bridges the two. Anything that breaks that bridge (no cloudflared binary, a proxy that blocks the tunnel protocol, an egress firewall rule) kills the session before your code ever runs.

Edge cases

• The first ever --remote run downloads cloudflared; if that download was interrupted you can be left with a corrupt binary, so reinstall it cleanly.
• VPNs that force all traffic through an inspecting proxy are a common cause; the tunnel protocol does not survive TLS interception.
• An old cloudflared on PATH can conflict with the one wrangler fetches; make sure only one is in play.
• Remote mode is for fidelity with production bindings; if you only need quick iteration on code, local mode is faster anyway.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_hSBz47cnriJK3RX2cst0sg