wrangler dev remote: cloudflared tunnel failed to establish

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

TL;DR: Get the real error by rerunning with debug logging, then clear the usual suspects. Silent startup death is almost always a stale .wrangler state directory, a Node version wrangler does not support, or a broken workerd binary. Debug output names the cause, and a clean state plus a fresh install fixes most cases.

wrangler dev local mode: workerd failed to start, no error output

1. Rerun with debug logging to see what is actually failing:

   wrangler dev --log-level debug

   Expected: verbose output showing where startup stops, such as a state directory path, a binary path, or a version complaint.

2. Check your Node version against what wrangler requires:

   node --version

   Expected: a supported LTS version. If it is older than what wrangler needs, upgrade Node first.

3. Clear the stale local state and retry:

   rm -rf .wrangler
   wrangler dev

   Expected: workerd starts cleanly. A corrupt state directory is the most common silent killer.

4. If it still dies silently, reinstall wrangler to replace a broken workerd binary:

   npm install -g wrangler@latest

   then retry step 3. Expected: the fresh binary starts without errors.

5. Check for a port or permission problem named in the debug output from step 1, such as the dev port already being bound or the binary lacking execute permission. Expected: the debug lines point at the specific resource, and freeing or fixing it lets startup proceed.

6. As a cross-check, run wrangler dev --remote once. If remote mode works while local mode does not, the problem is isolated to the local workerd runtime on your machine. Expected: remote works, confirming your worker code and config are fine and only the local runtime needs fixing.

Use this when

• wrangler dev exits or hangs at startup with no error message
• local mode fails but remote mode works
• the failure started after a wrangler upgrade, a Node upgrade, or a machine change
• the dev server worked yesterday and nothing in the project changed

Not for this skill when

• wrangler dev starts and then your worker code throws (that is a code error with a stack trace)
• the error message is present but cryptic (search the message itself instead)
• the dev server starts but requests fail (that is runtime behavior, not startup)
• remote mode fails too (that is config or auth, not the local runtime)

Variant phrasings

• wrangler dev workerd failed to start no error
• wrangler dev exits silently local mode
• workerd won't start wrangler dev blank output
• wrangler dev hangs on startup
• local dev workerd crashes immediately

Why it happens

Local mode shells out to the workerd binary and replays your worker inside it. If the binary cannot launch, the state it reads is corrupt, or the Node runtime driving wrangler is incompatible, the child process dies before it can print anything useful and wrangler reports the death without the cause. The debug flag surfaces the child's last words, and in practice the cause is almost always stale state, a bad binary, or a Node version mismatch.

Edge cases

• Deleting .wrangler wipes local KV, D1, and R2 emulator data. Back up anything in the emulators you care about before clearing.
• A globally installed wrangler and a project-local wrangler can disagree on the workerd version. Prefer the project-local one for consistency.
• Antivirus or corporate endpoint software sometimes quarantines the workerd binary after an update. If reinstalls keep breaking, check the quarantine list.
• On Apple Silicon versus Intel mismatches, a binary fetched for the wrong architecture fails silently. A clean reinstall on the same machine fetches the right one.
• If debug output shows the process being killed immediately, check available memory. An OOM kill at spawn looks exactly like a silent startup failure.

Provenance

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

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

Thread query: wrangler dev local mode: workerd failed to start, no error output

TL;DR:

Not specified by the original author.

wrangler dev: --remote flag requires authentication

TL;DR

Remote dev mode runs against your Cloudflare account, so wrangler needs to be logged in. Run wrangler login (or set the API token), then retry. Local mode needs no auth; remote does.

wrangler dev: --remote flag requires authentication

Steps

1. Run wrangler login and complete the browser flow, or export CLOUDFLAREAPITOKEN. Expected: Wrangler is authenticated.

2. Retry wrangler dev --remote. Expected: It starts.

3. For CI, use the API token (never interactive login). Expected: Automation works.

4. Check the token has the right permissions for the resources used. Expected: Scopes are sufficient.

5. Document the auth requirement for the team; local dev does not need it. Expected: Nobody is surprised again.

When to use

• wrangler dev --remote demands auth
• setting up remote dev
• CI runs of remote dev

When not to use

• using local dev mode (no auth needed)
• already logged in (check token expiry)
• the error is about something else (read it)

Tool compatibility

• wrangler
• dev --remote

Variant phrasings

• "wrangler dev remote requires authentication"
• "wrangler login remote dev"
• "--remote flag authentication"

Why it happens

Remote dev executes the worker on Cloudflare's infrastructure (for bindings and behavior parity), which requires account access. Local dev runs everything on your machine. The flag changes where the code runs, and where it runs determines whether auth is needed.

Edge cases

• API tokens need the right scopes; a token without them fails the same way
• wrangler logout/login cycles fix most stale-auth issues
• remote dev costs usage; it is not free like local

Provenance

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

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

Thread query: wrangler dev: --remote flag requires authentication

TL;DR: Remote dev mode runs against your Cloudflare account, so wrangler needs to be logged in. Run wrangler login (or set the API token), then retry. Local mode needs no auth; remote does.