diff --git a/npm-packages/convex/src/cli/deploy.ts b/npm-packages/convex/src/cli/deploy.ts
index 254ce76ef..5a26bd4c4 100644
--- a/npm-packages/convex/src/cli/deploy.ts
+++ b/npm-packages/convex/src/cli/deploy.ts
@@ -80,9 +80,11 @@ Same format as .env.local or .env files, and overrides them.`,
     const ctx = await oneoffContext(cmdOptions);
 
     const deploymentSelection = await getDeploymentSelection(ctx, cmdOptions);
+
+    const nonProdReason = isNonProdBuildEnvironment();
     if (
       cmdOptions.checkBuildEnvironment === "enable" &&
-      isNonProdBuildEnvironment() &&
+      nonProdReason &&
       deploymentSelection.kind === "existingDeployment" &&
       deploymentSelection.deploymentToActOn.source === "deployKey" &&
       deploymentSelection.deploymentToActOn.deploymentFields?.deploymentType ===
@@ -91,9 +93,7 @@ Same format as .env.local or .env files, and overrides them.`,
       await ctx.crash({
         exitCode: 1,
         errorType: "invalid filesystem data",
-        printedMessage: `Detected a non-production build environment and "${CONVEX_DEPLOY_KEY_ENV_VAR_NAME}" for a production Convex deployment.\n
-          This is probably unintentional.
-          `,
+        printedMessage: `${nonProdReason}\n\nDetected a non-production build environment and "${CONVEX_DEPLOY_KEY_ENV_VAR_NAME}" for a production Convex deployment.\nThis is probably unintentional.`,
       });
     }
 
diff --git a/npm-packages/convex/src/cli/lib/envvars.ts b/npm-packages/convex/src/cli/lib/envvars.ts
index 2eac3e2bd..7f922907f 100644
--- a/npm-packages/convex/src/cli/lib/envvars.ts
+++ b/npm-packages/convex/src/cli/lib/envvars.ts
@@ -340,14 +340,21 @@ export function gitBranchFromEnvironment(): string | null {
   return null;
 }
 
-export function isNonProdBuildEnvironment(): boolean {
+// -------------------------------------------------------------
+// Improved: Return detailed reason for non-production builds
+// -------------------------------------------------------------
+export function isNonProdBuildEnvironment(): string | null {
   if (process.env.VERCEL) {
     // https://vercel.com/docs/projects/environment-variables/system-environment-variables
-    return process.env.VERCEL_ENV !== "production";
+    if (process.env.VERCEL_ENV !== "production") {
+      return `Detected VERCEL because the VERCEL env var is set, but VERCEL_ENV is "${process.env.VERCEL_ENV}" instead of "production".`;
+    }
   }
   if (process.env.NETLIFY) {
     // https://docs.netlify.com/configure-builds/environment-variables/
-    return process.env.CONTEXT !== "production";
+    if (process.env.CONTEXT !== "production") {
+      return `Detected NETLIFY because the NETLIFY env var is set, but CONTEXT is "${process.env.CONTEXT}" instead of "production".`;
+    }
   }
-  return false;
+  return null; // everything looks production-safe
 }