Fail debounced workflow with ERROR instead of hanging when unregistered

Add recordErrorForUnstartedWorkflow so awaiting handles fail fast; validate registration up front in Debouncer.

Author: easmith

transact/src/main/java/dev/dbos/transact/database/SystemDatabase.java

@@ -359,6 +359,14 @@ public void recordWorkflowError(String workflowId, String error) {
     dbRetry(() -> WorkflowDAO.recordWorkflowError(ctx, workflowId, error));
   }
 
+  /**
+   * Insert a workflow_status row already in the ERROR state, for a workflow that was never started.
+   * See {@link WorkflowDAO#recordErrorForUnstartedWorkflow}.
+   */
+  public void recordErrorForUnstartedWorkflow(WorkflowStatusInternal initStatus, String error) {
+    dbRetry(() -> WorkflowDAO.recordErrorForUnstartedWorkflow(ctx, initStatus, error));
+  }
+
   public WorkflowStatus getWorkflowStatus(String workflowId) {
     return dbRetry(() -> WorkflowDAO.getWorkflowStatus(ctx, workflowId));
   }

transact/src/main/java/dev/dbos/transact/database/dao/WorkflowDAO.java

@@ -374,6 +374,28 @@ public static void recordWorkflowError(DbContext ctx, String workflowId, String
     }
   }
 
+  /**
+   * Insert a workflow_status row and immediately mark it ERROR, for a workflow that was never
+   * actually started. Used when an internal workflow that is responsible for starting a user
+   * workflow fails before it can do so: without a status row, any handle awaiting the user
+   * workflow would poll {@link #awaitWorkflowResult} forever.
+   *
+   * @param initStatus metadata for the workflow that will be recorded as failed
+   * @param error the error serialized as json
+   */
+  public static void recordErrorForUnstartedWorkflow(
+      DbContext ctx, WorkflowStatusInternal initStatus, String error) throws SQLException {
+
+    // No explicit transaction: the calling debouncer workflow is itself durable, so a crash
+    // between these two statements is replayed and retried. ON CONFLICT makes the insert
+    // idempotent and the outcome update is safe to repeat.
+    try (var conn = ctx.getConnection()) {
+      insertWorkflowStatus(conn, ctx.schema(), initStatus, UUID.randomUUID().toString(), false);
+      updateWorkflowOutcome(
+          conn, ctx.schema(), initStatus.workflowId(), WorkflowState.ERROR, null, error);
+    }
+  }
+
   public static String getWorkflowSerialization(DbContext ctx, String workflowId)
       throws SQLException {
     var sql =

transact/src/main/java/dev/dbos/transact/execution/DBOSExecutor.java

@@ -1882,4 +1882,50 @@ private void persistWorkflowError(String workflowId, Throwable error, String ser
     var serialized = SerializationUtil.serializeError(error, serialization, this.serializer);
     systemDatabase.recordWorkflowError(workflowId, serialized.serializedValue());
   }
+
+  /**
+   * Record an ERROR result for a workflow that was never started, so that handles awaiting it fail
+   * fast instead of polling forever. Used by internal workflows (e.g. the debouncer) that take
+   * responsibility for starting a user workflow and must surface their own failures to the caller's
+   * handle when they cannot.
+   */
+  public void recordErrorForUnstartedWorkflow(
+      String workflowId,
+      String workflowName,
+      String className,
+      @Nullable String instanceName,
+      @Nullable Object[] args,
+      Throwable error) {
+    String serialization = this.serializer.name();
+    var serializedArgs =
+        SerializationUtil.serializeArgs(
+            Objects.requireNonNullElseGet(args, () -> new Object[0]),
+            null,
+            serialization,
+            this.serializer);
+    var serializedError = SerializationUtil.serializeError(error, serialization, this.serializer);
+    var initStatus =
+        new WorkflowStatusInternal(
+            workflowId,
+            workflowName,
+            className,
+            instanceName,
+            null,
+            null,
+            null,
+            null,
+            null,
+            null,
+            null,
+            null,
+            serializedArgs.serializedValue(),
+            executorId(),
+            appVersion(),
+            appId(),
+            null,
+            null,
+            null,
+            serializedArgs.serialization());
+    systemDatabase.recordErrorForUnstartedWorkflow(initStatus, serializedError.serializedValue());
+  }
 }

transact/src/main/java/dev/dbos/transact/internal/DBOSIntegration.java

@@ -195,6 +195,23 @@ public RegisteredWorkflow registerInternalWorkflow(
     return executor("startRegisteredWorkflow").startRegisteredWorkflow(regWorkflow, args, options);
   }
 
+  /**
+   * Record a terminal ERROR for a workflow that was never started, so handles awaiting it fail
+   * fast instead of polling forever. Used by the built-in debouncer workflow when it cannot start
+   * the user workflow it is responsible for.
+   */
+  public void recordErrorForUnstartedWorkflow(
+      String workflowId,
+      String workflowName,
+      String className,
+      @Nullable String instanceName,
+      @Nullable Object[] args,
+      Throwable error) {
+    executor("recordErrorForUnstartedWorkflow")
+        .recordErrorForUnstartedWorkflow(
+            workflowId, workflowName, className, instanceName, args, error);
+  }
+
   /**
    * Execute a workflow method via its reflective {@link Method} handle. Intended for use by AOP
    * interceptors that capture workflow invocations at the proxy boundary.

transact/src/main/java/dev/dbos/transact/workflow/Debouncer.java

@@ -5,6 +5,7 @@
 import dev.dbos.transact.StartWorkflowOptions;
 import dev.dbos.transact.context.DBOSContextHolder;
 import dev.dbos.transact.exceptions.DBOSQueueDuplicatedException;
+import dev.dbos.transact.exceptions.DBOSWorkflowFunctionNotFoundException;
 import dev.dbos.transact.execution.DBOSExecutor;
 import dev.dbos.transact.execution.RegisteredWorkflow;
 import dev.dbos.transact.execution.ThrowingRunnable;
@@ -250,6 +251,15 @@ private <T, E extends Exception> WorkflowHandle<T, E> debounceInternal(
     }
     String userWorkflowId = ids.userWorkflowId();
     String messageId = ids.messageId();
+
+    // Fail fast for the common programmer error of debouncing an unregistered workflow. Without
+    // this the call would still succeed here and only fail later inside the debouncer workflow.
+    if (executor
+        .getRegisteredWorkflow(
+            invocation.workflowName(), invocation.className(), invocation.instanceName())
+        .isEmpty()) {
+      throw new DBOSWorkflowFunctionNotFoundException(userWorkflowId, invocation.workflowName());
+    }
     String debouncerDeduplicationId = invocation.workflowName() + "-" + debounceKey;
 
     DebouncerOptions options =

transact/src/main/java/dev/dbos/transact/workflow/internal/InternalWorkflows.java

@@ -3,6 +3,8 @@
 import dev.dbos.transact.Constants;
 import dev.dbos.transact.DBOS;
 import dev.dbos.transact.StartWorkflowOptions;
+import dev.dbos.transact.exceptions.DBOSWorkflowFunctionNotFoundException;
+import dev.dbos.transact.execution.RegisteredWorkflow;
 
 import java.lang.reflect.Method;
 import java.time.Duration;
@@ -82,20 +84,33 @@ public void debouncerWorkflow(
       dbos.setEvent(next.messageId(), next.messageId());
     }
 
-    var workflow =
+    Optional<RegisteredWorkflow> optWorkflow =
         dbos.integration()
             .getRegisteredWorkflow(
-                options.workflowName(), options.className(), options.instanceName())
-            .orElseThrow(
-                () ->
-                    new IllegalStateException(
-                        "Debouncer cannot find registered user workflow: "
-                            + options.workflowName()
-                            + " / "
-                            + options.className()
-                            + (options.instanceName() == null
-                                ? ""
-                                : " / " + options.instanceName())));
+                options.workflowName(), options.className(), options.instanceName());
+    if (optWorkflow.isEmpty()) {
+      // The user workflow is not registered in this process (e.g. it was renamed/removed, or we
+      // are recovering on a build that no longer declares it). We can never start it, so record
+      // a terminal ERROR for the pre-assigned user workflow id. Otherwise any handle returned to
+      // the caller would poll getResult() forever, since the status row would never appear.
+      var notFound =
+          new DBOSWorkflowFunctionNotFoundException(ctx.userWorkflowId(), options.workflowName());
+      logger.error(
+          "Debouncer cannot find registered user workflow {} (id={}); recording ERROR",
+          options.workflowName(),
+          ctx.userWorkflowId(),
+          notFound);
+      dbos.integration()
+          .recordErrorForUnstartedWorkflow(
+              ctx.userWorkflowId(),
+              options.workflowName(),
+              options.className(),
+              options.instanceName(),
+              latestArgs,
+              notFound);
+      return;
+    }
+    var workflow = optWorkflow.get();
 
     // priority and deduplicationId are only valid for queued workflows; the executor
     // throws IllegalArgumentException if they are set without a queue name.

transact/src/test/java/dev/dbos/transact/client/DebouncerClientTest.java

@@ -108,7 +108,7 @@ void differentKeysFireIndependently() throws Exception {
   }
 
   @Test
-  void reDebouncAfterWindowCloses() throws Exception {
+  void reDebounceAfterWindowCloses() throws Exception {
     var d = debouncer();
 
     var h1 = d.debounce("key-r", Duration.ofMillis(300), "first");

transact/src/test/java/dev/dbos/transact/workflow/DebouncerTest.java

@@ -337,7 +337,7 @@ public void explicitPriorityForwardedToUserWorkflow() throws Exception {
   // Regression test for: deduplication_id is cleared to NULL on completion, so the UNIQUE
   // constraint no longer blocks a new enqueue with the same key.
   @Test
-  public void reDebouncAfterWindowCloses() throws Exception {
+  public void reDebounceAfterWindowCloses() throws Exception {
     DebouncedService svc = dbos.registerProxy(DebouncedService.class, serviceImpl);
     dbos.launch();