ContextQMD
Back to Mastra

Reference: Run.cancel() | Workflows

docs/src/content/en/reference/workflows/run-methods/cancel.mdx

2025-12-182.5 KB
Original Source

Run.cancel()

The .cancel() method cancels a workflow run, stopping execution and cleaning up resources.

This method aborts any running steps and updates the workflow status to 'canceled'. It works for both actively running workflows and suspended/waiting workflows.

Usage example

typescript
const run = await workflow.createRun()

await run.cancel()
// Returns: { message: 'Workflow run canceled' }

Parameters

<PropertiesTable content={[ { name: 'No parameters', type: 'void', description: 'This method takes no parameters', isOptional: false, }, ]} />

Returns

<PropertiesTable content={[ { name: 'result', type: 'Promise<{ message: string }>', description: "A promise that resolves with { message: 'Workflow run canceled' } when cancellation succeeds", }, ]} />

How cancellation works

When called, the workflow will:

  1. Trigger the abort signal - Uses the standard Web API AbortSignal to notify running steps
  2. Prevent subsequent steps - No further steps will be executed

Abort signal behavior

Steps that check the abortSignal parameter can respond to cancellation:

  • Steps can listen to the 'abort' event: abortSignal.addEventListener('abort', callback)
  • Steps can check if already aborted: if (abortSignal.aborted) { ... }
  • Useful for cancelling timeouts, network requests, or long-running operations

Note: Steps must actively check the abort signal to be canceled mid-execution. Steps that don't check the signal will run to completion, but subsequent steps won't execute.

Extended usage examples

Cancelling a workflow on error

typescript
const run = await workflow.createRun()

try {
  const result = await run.start({ inputData: { value: 'initial data' } })
} catch (error) {
  await run.cancel()
}

Creating a step that responds to cancellation

typescript
const step = createStep({
  id: 'long-running-step',
  execute: async ({ inputData, abortSignal, abort }) => {
    const timeout = new Promise(resolve => {
      const timer = setTimeout(() => resolve('done'), 10000)

      // Clean up if canceled
      abortSignal.addEventListener('abort', () => {
        clearTimeout(timer)
        resolve('canceled')
      })
    })

    const result = await timeout

    // Check if aborted after async operation
    if (abortSignal.aborted) {
      return abort() // Stop execution
    }

    return { result }
  },
})