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

Workflow SDK - Build durable, resilient, and observable workflows

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

`WorkflowRunFailedError` is thrown when awaiting `run.returnValue` on a workflow run whose status is `'failed'`. This indicates that the workflow encountered a fatal error during execution and cannot produce a return value.

The `cause` property holds the original thrown value, hydrated through the workflow serialization pipeline so its type identity (e.g. `FatalError`, `RetryableError`, custom `Error` subclasses), `cause` chain, and custom properties are preserved. Because any JavaScript value can be thrown, `cause` is typed as `unknown`, so narrow it with `instanceof Error` (or a more specific check) before accessing fields like `message`. The high-level error classification is exposed as the top-level `errorCode` property.

A failed 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: the remote failure reaches the caller immediately, and the caller catches a `WorkflowRunFailedError` rather than a retry-exhaustion wrapper. Errors from *failing to read* the run, such as a transport blip, stay retryable.

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

try {
  const result = await run.returnValue;
} catch (error) {
  if (WorkflowRunFailedError.is(error)) { // [!code highlight]
    if (error.cause instanceof Error) {
      console.error(`Run ${error.runId} failed:`, error.cause.message);
    }
    if (error.errorCode) {
      console.error("Error code:", error.errorCode);
    }
  }
}
```

## API signature

### Properties

<TSDoc
definition={`
interface WorkflowRunFailedError {
  /** The ID of the failed run. */
  runId: string;
  /**
   * The original thrown value from the failed workflow run, hydrated through
   * the workflow serialization pipeline. Preserves the original type identity
   * (Error subclasses, FatalError, custom classes with WORKFLOW_SERIALIZE,
   * etc.) and custom properties. Typed as \`unknown\` because any value can
   * be thrown, so narrow with \`instanceof Error\` before accessing fields.
   */
  cause: unknown;
  /** The high-level error category (e.g. \`USER_ERROR\`, \`RUNTIME_ERROR\`). */
  errorCode?: string;
  /**
   * Always \`true\`. A failed run is terminal, so a step that reads one is not
   * retried.
   */
  fatal: true;
  /** The error message. */
  message: string;
}
export default WorkflowRunFailedError;`}
/>

### Static methods

#### `WorkflowRunFailedError.is(value)`

Type-safe check for `WorkflowRunFailedError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.

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

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