Skip to content

Cancellation

Cancel task executions before they complete.

Cancel by Execution ID

Cancel a specific execution:

// Invoke and get execution ID
const executionId = await conductor.invoke(
  { name: "long-task" },
  { data: largeDataset }
);

// Cancel it
const cancelled = await conductor.cancel(executionId);
console.log(cancelled); // true if cancelled, false if already completed

Cancellation States

Pending execution:

  • Execution is marked as cancelled and failed
  • Error set to "Cancelled by user"
  • Never runs

Running execution:

  • ctx.signal is aborted on the next poll of the worker running it, within about one pollIntervalMs
  • Task should check signal and exit gracefully
  • Execution is marked as cancelled and fails once the task stops, even if it was about to sleep or invoke a child

Workflows:

  • Cancelling an execution also cancels the child it is waiting on with ctx.invokeAndWait(), and that child's own waited-on children
  • Every workflow waiting on a cancelled execution with ctx.invokeAndWait() fails with "Child execution failed: "
  • ctx.waitForResult() and { execution: id } branches of ctx.waitForAny() do not link the executions: cancelling the waiter leaves the awaited execution running, and a cancelled execution resolves the wait with a cancelled outcome
  • Executions started with ctx.invoke(..., { cancelWithParent: true }) are cancelled with the reason their parent ended with, when it is cancelled or fails permanently. This applies in any state and to their own linked children. A running parent cancels them once it has stopped

Graceful Cancellation

Cancellation is checked at step boundaries. If your task runs into a ctx.checkpoint() or ctx.step() while cancelled, it will stop the execution gracefully. For more fine-grained control, you can use the shutdown signal directly:

const processItems = conductor.createTask(
  { name: "process-batch" },
  { invocable: true },
  async (event, ctx) => {
    const { items } = event.payload;

    for (const item of items) {
      // Check if cancelled
      if (ctx.signal.aborted) {
        ctx.logger.info("Task cancelled, cleaning up...");
        await cleanup();
        throw new Error("Task was cancelled");
      }

      await processItem(item);
    }

    return { processed: items.length };
  }
);

Cancel with Reason

Provide a cancellation reason:

await conductor.cancel(executionId, {
  reason: "User requested cancellation"
});

The reason is stored in last_error.

Unschedule Dynamic Cron

For dynamically scheduled cron tasks, use ctx.unschedule():

// In a task handler
await ctx.unschedule(
  { name: "scheduled-task" },
  "schedule-name"
);

This cancels the current execution and prevents future ones.

See Cron Scheduling for details.

What's Next?