Skip to main content
You can cancel workflow runs that are pending or running.

Cancel a Workflow Run

Use the cancel() method on a workflow run handle:

Cancelable States

Only workflows in these states can be canceled: Attempting to cancel a completed or failed workflow throws an error:

Canceled Workflow Behavior

When a workflow is canceled:
  1. The status changes to canceled
  2. The worker releases the workflow (sets worker_id to null)
  3. The finished_at timestamp is set
If a workflow is mid-execution when canceled, the current step may complete, but no new steps will run on the next poll.

Checking Cancellation Status

After calling cancel(), you can verify the status:

Idempotent Cancellation

Canceling an already-canceled workflow returns successfully without error:

Use Cases

Common reasons to cancel workflows:
  • User-initiated cancellation - User decides to abort an operation
  • Timeout exceeded - External system determines the workflow took too long
  • Duplicate detection - Another workflow is already handling this work
  • Cleanup on shutdown - Cancel pending work when shutting down a service