wrangler dev vs deployed: the parity gaps that fake you out

TL;DR: A secret present locally but never uploaded is the number one "works locally" failure. - Use # wrangler dev vs deployed parity wrangler dev

wrangler dev vs deployed parity

wrangler dev runs your Worker in a local workerd with emulated bindings. It is close to production, not identical. The gaps:

Bindings

• Local dev uses local emulations or preview resources, not your production KV namespace / D1 database / R2 bucket, unless you configure otherwise. Writing test data in dev and expecting it in production (or vice versa) is the classic confusion.
• A binding missing its id in config may silently fall back or fail locally while working remotely. Always fill in ids.

Secrets and vars

• Local secrets come from .dev.vars (or .env, not both; .dev.vars wins and .env is ignored when both exist). Production secrets come from wrangler secret put / dashboard. A secret present locally but never uploaded is the number one "works locally" failure.
• Use secrets.required in config so a missing secret warns in dev instead of 500ing in production.

Routing

• wrangler dev serves on a local URL, not your routes. Route-pattern bugs (wrong specificity, missing route) only appear after deploy. Verify routes with a real deploy to a staging environment, not just dev.
• The Vite plugin path (vite dev) selects environments via CLOUDFLARE_ENV; plain wrangler dev uses --env. Mixing the two flags across tools selects different configs silently.

Errors

• Runtime errors surface in the dev console; in production they surface as error codes (1101 worker threw, 1102 CPU exceeded) in Workers Logs / Tail. Set up log viewing before you need it, not after the first 1101.

Checklist

• Pre-deploy: secrets uploaded, binding ids present, routes verified on a staging deploy.
• Post-deploy: hit the real URL, check logs, confirm the code path that dev never exercised (cron, queue consumer, WebSocket).

When to use

You hit exactly this: wrangler dev vs deployed: the parity gaps that fake you out in wrangler dev vs deployed.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

wrangler dev vs deployed.

Edge cases

• in config may silently fall back or fail locally while working remotely.
• Mixing the two flags across tools selects different configs silently. ## Errors - Runtime errors surface in the dev console; in production they surface as error codes (1101 worker threw, 1102 CPU exceeded) in Workers Logs / Tail.

Verified against the live docs: .dev.vars/.env exclusivity and secrets.required from the Secrets doc, CLOUDFLARE_ENV vs --env from the Environments reference, error codes 1101/1102 from the Workers errors doc. Refs: https://developers.cloudflare.com/workers/configuration/secrets/, https://developers.cloudflare.com/workers/wrangler/environments/, https://developers.cloudflare.com/workers/observability/errors/