First deploy of a new Worker with secrets.required: every suggested remedy fails (secret put -> 10007, .dev.vars/env -> blocked or 10057), while the one working path (--secrets-file) is never mentioned

[joshua92y]

Environment

• wrangler 4.99.0, Windows 11
• Observed both via opennextjs-cloudflare deploy (plain wrangler deploy code path) on a real app, and via a minimal repro (below)
• wrangler.jsonc contains secrets: { required: ["TEST_SECRET"] }; the Worker has never been deployed

What we observed (minimal repro matrix)

Minimal Worker (worker.js + the config above), fresh name, one secret supplied per attempt:

How the secret value was supplied	First-deploy result
not supplied	pre-deploy validation error (expected)
wrangler secret put TEST_SECRET — the remedy the error suggests	impossible: Worker does not exist yet (code: 10007)
.dev.vars — suggested by the validation warning	blocked by the same pre-deploy validation; wrangler deploy does not read .dev.vars
TEST_SECRET in process.env — suggested by the validation warning	blocked by the same pre-deploy validation in the minimal repro
wrangler deploy --secrets-file secrets.env — mentioned nowhere in the guidance	✅ succeeds — Worker created, secret uploaded with the version

On a real app (deploying through opennextjs-cloudflare deploy), the env-supplied attempt got further — wrangler logged Using secrets defined in process.env — and then failed at the API with:

X [ERROR] A request to the Cloudflare API (/accounts/.../workers/scripts/<name>/versions) failed.
  cannot inherit bindings: no previous version exists [code: 10057]

i.e. the supplied secret was routed through the binding-inherit path, which cannot work when no previous version exists.

Why this is a problem

1. The guidance points only at paths that don't work for a first deploy. The pre-deploy error says "Use wrangler secret put <NAME> to set secrets before deploying" — impossible for a new Worker (10007). The validation warning says "Add them to .dev.vars, .env, or set as environment variables" — .dev.vars is not read by deploy, and the env path is either blocked by the same validation or ends in code: 10057 via the inherit path.

2. The one path that does work — --secrets-file — is not mentioned in any of these messages. Before discovering it, the only escape we found was: temporarily delete the secrets block → deploy → wrangler secret put → restore the block, which defeats the purpose of the gate for exactly one deploy.

3. When a secret value is supplied via env, sending it through the inherit path (instead of creating a new secret binding, as --secrets-file does) looks like a routing bug on the first-deploy path.

Suggested resolution (any of)

• Make the first-deploy validation/error messages mention --secrets-file, and drop .dev.vars/.env from the deploy-time guidance if deploy does not read them
• Or: route env/.dev.vars-supplied required secrets through the same "new secret binding" path that --secrets-file uses, so the documented remedies actually work

Repro

1. wrangler.jsonc: { "name": "<fresh-name>", "main": "worker.js", "compatibility_date": "2026-06-01", "secrets": { "required": ["TEST_SECRET"] } }
2. worker.js: export default { fetch() { return new Response("ok"); } };
3. TEST_SECRET=x wrangler deploy → blocked (or code: 10057 via the inherit path in larger setups)
4. wrangler secret put TEST_SECRET → code: 10007
5. echo TEST_SECRET=x > s.env && wrangler deploy --secrets-file s.env → succeeds

[jamesopstad]

Hi @joshua92y.

wrangler secret put TEST_SECRET — the remedy the error suggests | impossible: Worker does not exist yet (code: 10007)

I can't reproduce this. When I run wrangler secret put TEST_SECRET for a Worker that hasn't been deployed yet I get the following and accepting creates a stub Worker with the secret set.

Does the Worker name definitely match the one you are trying to deploy?

.dev.vars and process.env are only relevant to development here and you should only be prompted to set those when running wrangler dev rather than wrangler deploy.

[joshua92y]

Hi @jamesopstad,

Thanks for taking the time to reproduce this. I went back and reproduced the whole thing end-to-end on Wrangler 4.99.0 (Windows, non-interactive shell), and I'd like to update my findings.

1. secret put on a non-existent Worker — you're right, and my original report was incorrect.

With a fresh Worker name, wrangler secret put TEST_SECRET --name <fresh> creates the Worker stub and uploads the secret — both when piping a value and when piping nothing:

🌀 Creating the secret for the Worker "egen-repro14258-b"
? There doesn't seem to be a Worker called "egen-repro14258-b". Do you want to create a new Worker...?
🤖 Using fallback value in non-interactive context: yes
🌀 Creating new Worker "egen-repro14258-b"...
✨ Success! Uploaded secret TEST_SECRET

So the 10007 → stub creation path works exactly as you described, including in a non-interactive environment. I can no longer reproduce the 10007 from my original report, so I'm withdrawing that part — it was almost certainly a name/account-state mismatch on my side rather than the documented flow failing.

2. .dev.vars / process.env guidance — also correct.

I confirmed the .dev.vars / .env suggestion is strictly a development-only path. The message

Add them to .dev.vars, .env, or set as environment variables.

comes from getVarsForDev (dev/dev-vars.ts) and is only used by wrangler dev. The deployment path instead goes through addRequiredSecretsInheritBindings (secrets-validation.ts), which only emits:

Use `wrangler secret put <NAME>` to set secrets before deploying.

I had incorrectly conflated those two code paths.

What still seems worth improving — the deployment error message itself.

For a first deployment, the current error is simply:

X [ERROR] The following required secrets have not been set: TEST_SECRET

  Use `wrangler secret put <NAME>` to set secrets before deploying.

However, wrangler deploy --name <fresh> --secrets-file secrets.env already performs the complete first-deployment flow in a single command: it creates the Worker (if necessary), uploads the secrets, and deploys successfully. I verified the resulting Worker contains the expected secret_text binding.

wrangler secret put is also a valid solution, but it requires an extra command and creates a stub Worker first. (For completeness: secret put followed by deploy also works end-to-end — the inherited secret resolves and deploy doesn't hit 10057.) Because of that, --secrets-file feels like the most natural recommendation for an initial deployment, yet it isn't mentioned anywhere in the error message.

So my request is much narrower than the original report:

Consider mentioning --secrets-file alongside wrangler secret put in the messages emitted by addRequiredSecretsInheritBindings / handleMissingSecretsError.

A smaller, separate observation.

Values coming from process.env are not turned into secret bindings during deployment. The only ways to supply a secret value at deploy time are --secrets-file (which creates a secret_text binding) or --var (plain text). As a result, on an existing Worker, a required secret supplied only through process.env falls back to { type: "inherit" }, which produces 10057 if no previous Worker version contains that secret. That mismatch between "set an environment variable" and what deploy actually consumes is what originally led me down this debugging path.

[petebacondarwin]

I have a PR up to improve the error messages.

Regarding this:

A smaller, separate observation.

Values coming from process.env are not turned into secret bindings during deployment. The only ways to supply a secret value at deploy time are --secrets-file (which creates a secret_text binding) or --var (plain text). As a result, on an existing Worker, a required secret supplied only through process.env falls back to { type: "inherit" }, which produces 10057 if no previous Worker version contains that secret. That mismatch between "set an environment variable" and what deploy actually consumes is what originally led me down this debugging path.

This confusion was one of the reasons why we originally only supported .dev.vars file (rather than .env) to provide "development time only" variables (e.g. local dev secrets). The name was chosen to make it clear that this was dev only and not production.

By now supporting .env and also putting these values onto process.env in the Worker, it is easy to see how one might expect these values to be sent along with deployment to production.