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 — 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.

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)) { 
    if (error.cause instanceof Error) {
      console.error(`Run ${error.runId} failed:`, error.cause.message);
    }
    if (error.errorCode) {
      console.error("Error code:", error.errorCode);
    }
  }
}

Properties

Static Methods

WorkflowRunFailedError.is(value)

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

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

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