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

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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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