Cloudflare Workers "workerd ... failed to start" in CI

Miniflare and wrangler dev launch the workerd runtime binary. If workerd cannot start (an incompatible binary for the runner architecture, a bad config, or a fatal validation error), the test harness fails before the worker runs.

What this error means

A Workers test or wrangler dev in CI fails with "Failed to start workerd" or a "workerd/server/server.c++: Fatal" line, sometimes with an exec format or config validation error.

[mf:err] Error: Failed to start workerd
workerd/server/server.c++: Fatal: config validation failed

Common causes

workerd binary does not match the runner architecture

The installed workerd (via wrangler/miniflare) is built for a different CPU architecture than the runner, so it fails to exec.

Invalid runtime configuration

A malformed wrangler.toml, an unknown compatibility flag, or a binding that references a missing resource makes workerd reject the config at startup.

How to fix it

Install the matching workerd build

1. Reinstall dependencies on the runner so the correct workerd platform binary is fetched.
2. Confirm the runner architecture matches the installed binary.
3. Re-run the Workers test.

rm -rf node_modules && npm ci

Fix the wrangler config

Validate wrangler.toml and remove unknown flags or dangling bindings so workerd accepts the config.

npx wrangler deploy --dry-run --outdir dist

How to prevent it

• Reinstall dependencies on the target architecture in CI.
• Validate wrangler.toml with a dry run before tests.
• Keep compatibility flags to known, supported values.

Related guides