Improve 'wrangler secret put' error message when using Worker versions (#11882)

GregBrimble · web-flow · commit 695b043b4ddc · 2026-01-13T15:22:15.000-05:00
diff --git a/.changeset/ten-pants-wash.md b/.changeset/ten-pants-wash.md
@@ -0,0 +1,5 @@
+---
+"wrangler": patch
+---
+
+Improve the error message for `wrangler secret put` when using Worker versions or gradual deployments. `wrangler versions secret put` should be used instead, or ensure to deploy the latest version before using `wrangler secret put`. `wrangler secret put` alone will add the new secret to the latest version (possibly undeployed) and immediately deploy that which is usually not intended.
diff --git a/packages/wrangler/src/__tests__/secret.test.ts b/packages/wrangler/src/__tests__/secret.test.ts
@@ -547,9 +547,12 @@ describe("wrangler secret", () => {
 
 			await expect(runWrangler(`secret put secret-name --name ${scriptName}`))
 				.rejects.toThrowErrorMatchingInlineSnapshot(`
-				[Error: Secret edit failed. You attempted to modify a secret, but the latest version of your Worker isn't currently deployed. Please ensure that the latest version of your Worker is fully deployed (wrangler versions deploy) before modifying secrets. Alternatively, you can use the Cloudflare dashboard to modify secrets and deploy the version.
-
-				Note: This limitation will be addressed in an upcoming release.]
+				[Error: Secret edit failed. You attempted to modify a secret, but the latest version of your Worker isn't currently deployed.
+				This limitation exists to prevent accidental deployment when using Worker versions and secrets together.
+				To resolve this, you have two options:
+				(1) use the \`wrangler versions secret put\` instead, which allows you to update secrets without deploying; or
+				(2) deploy the latest version first, then modify secrets.
+				Alternatively, you can use the Cloudflare dashboard to modify secrets and deploy the version.]
 			`);
 		});
 	});
diff --git a/packages/wrangler/src/secret/index.ts b/packages/wrangler/src/secret/index.ts
@@ -216,11 +216,12 @@ export const secretPutCommand = createCommand({
 			} catch (e) {
 				if (e instanceof APIError && e.code === VERSION_NOT_DEPLOYED_ERR_CODE) {
 					throw new UserError(
-						"Secret edit failed. You attempted to modify a secret, but the latest version of your Worker isn't currently deployed. " +
-							"Please ensure that the latest version of your Worker is fully deployed " +
-							"(wrangler versions deploy) before modifying secrets. " +
-							"Alternatively, you can use the Cloudflare dashboard to modify secrets and deploy the version." +
-							"\n\nNote: This limitation will be addressed in an upcoming release."
+						"Secret edit failed. You attempted to modify a secret, but the latest version of your Worker isn't currently deployed.\n" +
+							"This limitation exists to prevent accidental deployment when using Worker versions and secrets together.\n" +
+							"To resolve this, you have two options:\n" +
+							"(1) use the `wrangler versions secret put` instead, which allows you to update secrets without deploying; or\n" +
+							"(2) deploy the latest version first, then modify secrets.\n" +
+							"Alternatively, you can use the Cloudflare dashboard to modify secrets and deploy the version."
 					);
 				} else {
 					throw e;

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"wrangler": patch
 +---
++
 +Improve the error message for `wrangler secret put` when using Worker versions or gradual deployments. `wrangler versions secret put` should be used instead, or ensure to deploy the latest version before using `wrangler secret put`. `wrangler secret put` alone will add the new secret to the latest version (possibly undeployed) and immediately deploy that which is usually not intended.