Worker works in dev, fails in production: the environment checklist

TL;DR

Secrets are set with wrangler secret put, never in the Wrangler file. The classic failure: the secret exists in your local.dev.vars (or your shell) but was never set on the deployed Worker, so production throws on first use. Then wrangler deploy fails with a clear error if any required secret is not configured, instead of the Worker failing at runtime.

When to use

You are seeing this: wrangler dev is forgiving in ways production is not. Use this skill when you run into "Worker works in dev, fails in production: the environment checklist".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

wrangler dev is forgiving in ways production is not. When dev works and production fails, check the environment differences systematically:

Secrets

Secrets are set with wrangler secret put, never in the Wrangler file. The classic failure: the secret exists in your local .dev.vars (or your shell) but was never set on the deployed Worker, so production throws on first use.

Prevention: declare required secret names in the Wrangler file's secrets configuration property. Then wrangler deploy fails with a clear error if any required secret is not configured, instead of the Worker failing at runtime. Note that wrangler secret put creates a new version of the Worker and deploys it immediately: setting a secret is a deploy.

Bindings per environment

Each [env.*] needs its own bindings. A binding that exists at top level but not under [env.production] (or vice versa) means production code references env.DB and gets undefined. Diff the environments' bindings before debugging code.

Compatibility date

wrangler dev and the deployed Worker can behave differently if the compatibility date changed between test and deploy, or if local dev ran with different flags. Pin the date, and know that dates 2026-08-04 and later enable nodejs_compat behavior by default.

Checklist

• Declare required secrets; let deploy fail loudly instead of runtime failing silently.
• Diff bindings across environments.
• After any secret change, remember it redeployed the Worker: verify the new version is the one serving.

Verified against the live Workers secrets doc: secrets config property fails deploy when required secrets missing, wrangler secret put deploys immediately. And compat dates doc: 2026-08-04+ enables nodejs_compat by default. Refs: https://developers.cloudflare.com/workers/configuration/secrets/ and https://developers.cloudflare.com/workers/configuration/compatibility-dates/