workflow/docs/api-reference/workflow-errors/workflow-run-cancelled-error.mdx

Workflow SDK - Build durable, resilient, and observable workflows

---
title: WorkflowRunCancelledError
description: Thrown when awaiting the return value of a canceled workflow run.
type: reference
summary: Catch WorkflowRunCancelledError when awaiting run.returnValue on a run that was canceled.
related:
  - /docs/api-reference/workflow-errors/workflow-run-failed-error
  - /docs/api-reference/workflow-errors/workflow-run-not-found-error
---

`WorkflowRunCancelledError` is thrown when awaiting `run.returnValue` on a workflow run that was explicitly canceled via `run.cancel()`. Canceled runs do not produce a return value.

You can check for cancellation before awaiting by inspecting `run.status`.

A canceled run is terminal, so this error is non-retryable (`fatal: true`). Inside a workflow, `await run.returnValue` runs as a step, and that step fails on its first attempt instead of spending its retry budget re-reading a run that cannot change. Errors from *failing to read* the run, such as a transport blip, stay retryable.

```typescript lineNumbers
import { WorkflowRunCancelledError } from "workflow/errors"
declare const run: { status: Promise<string>; returnValue: Promise<any> }; // @setup

try {
  const result = await run.returnValue;
} catch (error) {
  if (WorkflowRunCancelledError.is(error)) { // [!code highlight]
    console.log(`Run ${error.runId} was cancelled`);
  }
}
```

## API signature

### Properties

<TSDoc
definition={`
interface WorkflowRunCancelledError {
  /** The ID of the canceled run. */
  runId: string;
  /**
   * Always \`true\`. A canceled run is terminal, so a step that reads one is
   * not retried.
   */
  fatal: true;
  /** The error message. */
  message: string;
}
export default WorkflowRunCancelledError;`}
/>

### Static methods

#### `WorkflowRunCancelledError.is(value)`

Type-safe check for `WorkflowRunCancelledError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.

```typescript
import { WorkflowRunCancelledError } from "workflow/errors"
declare const error: unknown; // @setup

if (WorkflowRunCancelledError.is(error)) {
  // error is typed as WorkflowRunCancelledError
}
```