feat(deploy): recover from production_instance_exists by resuming live state

Author: wyattjoh

packages/cli-core/src/commands/deploy/index.test.ts

@@ -3,7 +3,7 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { tmpdir } from "node:os";
 import { captureLog, promptsStubs, listageStubs } from "../../test/lib/stubs.ts";
-import { CliError, EXIT_CODE, UserAbortError } from "../../lib/errors.ts";
+import { CliError, EXIT_CODE, PlapiError, UserAbortError } from "../../lib/errors.ts";
 
 const mockIsAgent = mock();
 let _modeOverride: string | undefined;
@@ -40,6 +40,8 @@ type DeployApiMockOptions = {
   failCreateProductionInstance?: boolean;
   failDnsVerification?: boolean;
   failOAuthSave?: boolean;
+  failValidateCloningUnsupportedFeatures?: string[];
+  failCreateProductionInstanceExists?: boolean;
 };
 
 let mockDeployApiOptions: DeployApiMockOptions = {};
@@ -53,6 +55,18 @@ function simulatedDeployApiFailure(step: string): Error {
   return new Error(`Simulated deploy failure: ${step}.`);
 }
 
+function simulatedSpecificFailure(
+  status: number,
+  code: string,
+  message: string,
+  meta?: Record<string, unknown>,
+): PlapiError {
+  const body = JSON.stringify({
+    errors: [{ code, message, ...(meta ? { meta } : {}) }],
+  });
+  return PlapiError.fromBody(status, body, "clerk deploy test mock");
+}
+
 mock.module("@inquirer/prompts", () => ({
   ...promptsStubs,
   select: (...args: unknown[]) => mockSelect(...args),
@@ -85,13 +99,28 @@ mock.module("../../lib/plapi.ts", () => ({
 mock.module("./api.ts", () => ({
   configureMockDeployApi,
   createProductionInstance: (...args: unknown[]) => {
+    if (mockDeployApiOptions.failCreateProductionInstanceExists) {
+      throw simulatedSpecificFailure(
+        400,
+        "production_instance_exists",
+        "You can only have one production instance.",
+      );
+    }
     const result = mockCreateProductionInstance(...args);
     if (mockDeployApiOptions.failCreateProductionInstance) {
       throw simulatedDeployApiFailure("production instance creation");
     }
     return result;
   },
   validateCloning: (...args: unknown[]) => {
+    if (mockDeployApiOptions.failValidateCloningUnsupportedFeatures) {
+      throw simulatedSpecificFailure(
+        402,
+        "unsupported_subscription_plan_features",
+        "Unsupported plan features",
+        { unsupported_features: mockDeployApiOptions.failValidateCloningUnsupportedFeatures },
+      );
+    }
     const result = mockValidateCloning(...args);
     if (mockDeployApiOptions.failValidateCloning) {
       throw simulatedDeployApiFailure("cloning validation");
@@ -1446,5 +1475,66 @@ describe("deploy", () => {
       expect(err).toContain("facebook");
       expect(err).toContain("Configure them from the Clerk Dashboard before going live");
     });
+
+    test("recovers from production_instance_exists by resuming reconcileExistingDeploy", async () => {
+      _modeOverride = "human";
+      await linkedProject({
+        appId: "app_test",
+        appName: "Test App",
+        instances: { development: "ins_dev" },
+      });
+      // First call (resolveDeployContext): no production instance yet.
+      // Second call (reloadProductionState after recovery): production instance exists.
+      mockFetchApplication
+        .mockResolvedValueOnce({
+          application_id: "app_test",
+          name: "Test App",
+          instances: [
+            { instance_id: "ins_dev", environment_type: "development", publishable_key: "pk_test" },
+          ],
+        })
+        .mockResolvedValueOnce({
+          application_id: "app_test",
+          name: "Test App",
+          instances: [
+            { instance_id: "ins_dev", environment_type: "development", publishable_key: "pk_test" },
+            {
+              instance_id: "ins_prod_existing",
+              environment_type: "production",
+              publishable_key: "pk_live",
+            },
+          ],
+        });
+      mockListApplicationDomains.mockResolvedValue({
+        data: [
+          {
+            object: "domain",
+            id: "dmn_existing",
+            name: "example.com",
+            is_satellite: false,
+            is_provider_domain: false,
+            frontend_api_url: "https://clerk.example.com",
+            development_origin: "",
+            cname_targets: [],
+            created_at: "2026-05-12T00:00:00Z",
+            updated_at: "2026-05-12T00:00:00Z",
+          },
+        ],
+        total_count: 1,
+      });
+      mockGetDeployStatus.mockResolvedValue({ status: "complete" });
+      mockFetchInstanceConfig.mockResolvedValue({});
+      mockConfirm.mockResolvedValue(true);
+      mockInput.mockResolvedValueOnce("example.com");
+
+      captured = captureLog();
+      await runDeploy({ testFailCreateProductionInstanceExists: true });
+
+      expect(captured.err).toContain(
+        "A production instance already exists for this application. Resuming",
+      );
+      // Confirm reconcile path ran (plan renders "Use production domain").
+      expect(captured.err).toContain("Use production domain example.com");
+    });
   });
 });

packages/cli-core/src/commands/deploy/index.ts

@@ -2,7 +2,13 @@ import { isAgent } from "../../mode.ts";
 import { isInsideGutter, log } from "../../lib/log.ts";
 import { sleep } from "../../lib/sleep.ts";
 import { bar, intro, outro, withSpinner } from "../../lib/spinner.ts";
-import { UserAbortError, isPromptExitError, throwUsageError } from "../../lib/errors.ts";
+import {
+  CliError,
+  PlapiError,
+  UserAbortError,
+  isPromptExitError,
+  throwUsageError,
+} from "../../lib/errors.ts";
 import { resolveProfile, setProfile } from "../../lib/config.ts";
 import {
   fetchApplication,
@@ -74,6 +80,7 @@ type DeployOptions = {
   testFailDomainLookup?: boolean;
   testFailValidateCloning?: boolean;
   testFailCreateProductionInstance?: boolean;
+  testFailCreateProductionInstanceExists?: boolean;
   testFailDnsVerification?: boolean;
   testFailOAuthSave?: boolean;
 };
@@ -169,6 +176,7 @@ function configureDeployApiMocks(testFlags: DeployTestFlags): void {
   configureMockDeployApi({
     failValidateCloning: testFlags.testFailValidateCloning,
     failCreateProductionInstance: testFlags.testFailCreateProductionInstance,
+    failCreateProductionInstanceExists: testFlags.testFailCreateProductionInstanceExists,
     failDnsVerification: testFlags.testFailDnsVerification,
     failOAuthSave: testFlags.testFailOAuthSave,
   });
@@ -255,7 +263,18 @@ async function startNewDeploy(ctx: DeployContext): Promise<void> {
   );
   if (!shouldCreateProductionInstance) return;
 
-  const production = await createProductionInstance(ctx, domain);
+  let production: ProductionInstanceResponse;
+  try {
+    production = await createProductionInstance(ctx, domain);
+  } catch (error) {
+    if (error instanceof PlapiError && error.code === "production_instance_exists") {
+      log.info("A production instance already exists for this application. Resuming…");
+      const reconciledCtx = await reloadProductionState(ctx);
+      await reconcileExistingDeploy(reconciledCtx);
+      return;
+    }
+    throw error;
+  }
   await persistProductionInstance(ctx, production.instance_id);
   log.blank();
 
@@ -759,6 +778,30 @@ async function collectAndSaveOAuthCredentials(
   return true;
 }
 
+/**
+ * Refresh the deploy context from the server after a recovery branch.
+ *
+ * Used when the server tells us a production instance exists but our local
+ * context doesn't know about it yet (e.g. state was lost between runs). Pulls
+ * the application down again, finds the production instance, and persists the
+ * resolved ID so subsequent `clerk deploy` invocations short-circuit to
+ * `reconcileExistingDeploy` directly.
+ */
+async function reloadProductionState(ctx: DeployContext): Promise<DeployContext> {
+  const app = await fetchApplication(ctx.appId);
+  const production = app.instances.find((entry) => entry.environment_type === "production");
+  if (!production) {
+    throw new CliError(
+      "Server reports a production instance exists but did not return one when refetching the application.",
+    );
+  }
+  await persistProductionInstance(ctx, production.instance_id);
+  return {
+    ...ctx,
+    productionInstanceId: production.instance_id,
+  };
+}
+
 async function persistProductionInstance(ctx: DeployContext, productionInstanceId: string) {
   await setProfile(ctx.profileKey, {
     ...ctx.profile,