[wrangler] Fix first-deploy guidance for required secrets (#14332)

Author: Divkix

.changeset/fix-required-secrets-first-deploy-guidance.md

@@ -0,0 +1,11 @@
+---
+"wrangler": patch
+---
+
+Fix misleading error guidance when deploying a new Worker with `secrets.required`
+
+When a Worker declares `secrets.required` and has never been deployed before, the previous error message suggested running `wrangler secret put <NAME>`, which doesn't work because the Worker doesn't exist yet.
+
+The one path that does work — `wrangler deploy --secrets-file <path>` — was not mentioned anywhere in the error output.
+
+The pre-deploy error now explains that `wrangler secret put` cannot be used for a new Worker, and directs users to the `--secrets-file` flag instead. The post-deploy error for existing Workers now also mentions `--secrets-file` alongside `wrangler secret put`.

packages/deploy-helpers/src/deploy/helpers/secrets-validation.ts

@@ -34,9 +34,12 @@ export function addRequiredSecretsInheritBindings(
 	if (options.type === "deploy" && !options.workerExists) {
 		throw new UserError(
 			`The following required secrets have not been set: ${inheritedSecrets.join(", ")}\n` +
-				`Use \`wrangler secret put <NAME>\` to set secrets before deploying.\n` +
+				`This Worker does not exist yet, so secrets cannot be set in advance with \`wrangler secret put\`.\n` +
+				`To deploy a new Worker with secrets, supply them via a secrets file:\n` +
+				`  wrangler deploy --secrets-file <path-to-file>\n` +
+				`where the file contains lines in the format \`SECRET_NAME=value\` (or JSON).\n` +
 				`See https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-deployed-workers for more information.`,
-			{ telemetryMessage: "required secrets missing before deploy" }
+			{ telemetryMessage: "required secrets missing before first deploy" }
 		);
 	}
 
@@ -68,9 +71,13 @@ export function handleMissingSecretsError(
 
 	if (missingSecretNames.length > 0) {
 		err.preventReport();
+		const secretPutCommand = `wrangler ${options.type === "deploy" ? "" : "versions "}secret put`;
+		const secretsFileCommand = `wrangler ${options.type === "deploy" ? "deploy" : "versions upload"} --secrets-file <path-to-file>`;
+		const action = options.type === "deploy" ? "deploying" : "uploading";
 		throw new UserError(
 			`The following required secrets have not been set: ${missingSecretNames.join(", ")}\n` +
-				`Use \`wrangler ${options.type === "deploy" ? "secret put" : "versions secret put"} <NAME>\` to set secrets before ${options.type === "deploy" ? "deploying" : "uploading"}.\n` +
+				`Use \`${secretPutCommand} <NAME>\` to set secrets before ${action},\n` +
+				`or supply them when ${action} with \`${secretsFileCommand}\`.\n` +
 				`See https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-deployed-workers for more information.`,
 			{ telemetryMessage: "required secrets missing during upload or deploy" }
 		);

packages/wrangler/src/__tests__/deploy/secrets.test.ts

@@ -338,7 +338,8 @@ SECRET3=value3`
 				runWrangler("deploy index.js")
 			).rejects.toThrowErrorMatchingInlineSnapshot(
 				`[Error: The following required secrets have not been set: API_KEY, DB_PASSWORD
-Use \`wrangler secret put <NAME>\` to set secrets before deploying.
+Use \`wrangler secret put <NAME>\` to set secrets before deploying,
+or supply them when deploying with \`wrangler deploy --secrets-file <path-to-file>\`.
 See https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-deployed-workers for more information.]`
 			);
 		});
@@ -358,7 +359,10 @@ See https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-
 				runWrangler("deploy index.js")
 			).rejects.toThrowErrorMatchingInlineSnapshot(
 				`[Error: The following required secrets have not been set: API_KEY, DB_PASSWORD
-Use \`wrangler secret put <NAME>\` to set secrets before deploying.
+This Worker does not exist yet, so secrets cannot be set in advance with \`wrangler secret put\`.
+To deploy a new Worker with secrets, supply them via a secrets file:
+  wrangler deploy --secrets-file <path-to-file>
+where the file contains lines in the format \`SECRET_NAME=value\` (or JSON).
 See https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-deployed-workers for more information.]`
 			);
 		});
@@ -432,7 +436,10 @@ See https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-
 				runWrangler(`deploy --secrets-file ${secretsFile}`)
 			).rejects.toThrowErrorMatchingInlineSnapshot(
 				`[Error: The following required secrets have not been set: SECRET2, SECRET3
-Use \`wrangler secret put <NAME>\` to set secrets before deploying.
+This Worker does not exist yet, so secrets cannot be set in advance with \`wrangler secret put\`.
+To deploy a new Worker with secrets, supply them via a secrets file:
+  wrangler deploy --secrets-file <path-to-file>
+where the file contains lines in the format \`SECRET_NAME=value\` (or JSON).
 See https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-deployed-workers for more information.]`
 			);
 		});

packages/wrangler/src/__tests__/versions/secrets.test.ts

@@ -331,7 +331,8 @@ SECRET3=value3`
 				runWrangler(`versions upload --name ${workerName}`)
 			).rejects.toThrowErrorMatchingInlineSnapshot(
 				`[Error: The following required secrets have not been set: API_KEY, DB_PASSWORD
-Use \`wrangler versions secret put <NAME>\` to set secrets before uploading.
+Use \`wrangler versions secret put <NAME>\` to set secrets before uploading,
+or supply them when uploading with \`wrangler versions upload --secrets-file <path-to-file>\`.
 See https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-deployed-workers for more information.]`
 			);
 		});