Workers vars vs secrets: what goes where

TL;DR: # Vars vs secrets on Workers Two different mechanisms, and mixing them up leaks credentials into places you can see. ## Vars: plaintext, visible - Set in wrangler.jsonc under

Vars vs secrets on Workers

Two different mechanisms, and mixing them up leaks credentials into places you can see.

Vars: plaintext, visible

• Set in wrangler.jsonc under vars, or in the dashboard under Workers and Pages, Settings, Variables and Secrets, Add.
• Visible to anyone with dashboard or config access, and printed in some CLI output. Never put credentials here.
• vars is non-inheritable across environments: each [env.staging] / [env.production] must define its own. The top-level value does not flow down.

Secrets: encrypted, write-only

• Set with wrangler secret put MY_SECRET_VALUE or in the dashboard as a secret type. Values are encrypted and never displayed back.
• For local dev, put them in .dev.vars (or .env, not both) next to your Wrangler config, in dotenv format. If you define .dev.vars, .env values are ignored.
• You can declare required secret names with the secrets.required config property. When defined, only the listed keys load from .dev.vars/.env; anything extra is excluded and missing keys produce a warning. Use this so a missing secret fails loudly in dev instead of silently in production.

The binding angle

Both vars and secrets arrive on env in your code. The distinction is storage and visibility, not access. A secret read from env.MY_SECRET_VALUE is safe precisely because it was never in your config file or repo.

Checklist

• .dev.vars is gitignored. Always. Check before first commit.
• In CI, secrets come from the CI secret store into wrangler secret put, never from a checked-in file.
• After rotating a secret, remember isolate reuse: do not cache clients built from env secrets in global scope; construct per request.

When to use

You hit exactly this: Workers vars vs secrets: what goes where in Workers vars vs secrets.

When not to use

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

Compatibility

Workers vars vs secrets.

Verified against the live Secrets and Environment Variables docs: .dev.vars vs .env exclusivity, secrets.required allowlist behavior, dashboard path, vars non-inheritable. Refs: https://developers.cloudflare.com/workers/configuration/secrets/ and https://developers.cloudflare.com/workers/configuration/environment-variables/