workflow 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/api-reference/workflow-errors/index.mdx

@@ -0,0 +1,88 @@
+---
+title: "workflow/errors"
+description: Semantic error types thrown by the Workflow SDK and its storage backends.
+type: overview
+summary: Explore the error classes exported from workflow/errors for handling workflow failures.
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+API reference for the error classes exported from the `workflow/errors` package.
+
+All errors extend [`WorkflowError`](/docs/api-reference/workflow-errors/workflow-error), so you can catch any SDK error with a single `instanceof` check, or narrow to a specific class for fine-grained handling.
+
+## Base classes
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/workflow-error" title="WorkflowError">
+        Base class for all workflow error types.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-world-error" title="WorkflowWorldError">
+        Base error for failures from workflow storage backends.
+    </Card>
+</Cards>
+
+## Registration errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/workflow-not-registered-error" title="WorkflowNotRegisteredError">
+        Thrown when a workflow function is not registered in the current deployment.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/step-not-registered-error" title="StepNotRegisteredError">
+        Thrown when a step function is not registered in the current deployment.
+    </Card>
+</Cards>
+
+## Run errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-not-found-error" title="WorkflowRunNotFoundError">
+        Thrown when operating on a workflow run that does not exist.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-failed-error" title="WorkflowRunFailedError">
+        Thrown when awaiting the return value of a failed workflow run.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-cancelled-error" title="WorkflowRunCancelledError">
+        Thrown when awaiting the return value of a canceled workflow run.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-not-completed-error" title="WorkflowRunNotCompletedError">
+        Thrown when requesting the result of a workflow run that has not completed yet.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-runtime-error" title="WorkflowRuntimeError">
+        Thrown when the workflow runtime encounters an execution error, such as serialization failures or timeouts.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/run-expired-error" title="RunExpiredError">
+        Thrown when a workflow run has expired and can no longer be operated on.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/run-not-supported-error" title="RunNotSupportedError">
+        Thrown when a workflow run requires a newer workflow spec version than the installed SDK supports.
+    </Card>
+</Cards>
+
+## Hook errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/hook-not-found-error" title="HookNotFoundError">
+        Thrown when resuming a hook that does not exist.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/hook-conflict-error" title="HookConflictError">
+        Thrown when creating a hook with a token that is already in use by another workflow run.
+    </Card>
+</Cards>
+
+## Backend errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/throttle-error" title="ThrottleError">
+        Thrown when a request is rate-limited by the workflow backend.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/entity-conflict-error" title="EntityConflictError">
+        Thrown when a storage operation conflicts with the current entity state.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/precondition-failed-error" title="PreconditionFailedError">
+        Thrown when an event creation is rejected because the client's event-log snapshot is stale.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/too-early-error" title="TooEarlyError">
+        Thrown when a request is made before the system is ready to process it.
+    </Card>
+</Cards>

package/docs/api-reference/workflow-errors/meta.json

@@ -1,16 +1,22 @@
 {
   "title": "workflow/errors",
   "pages": [
+    "workflow-error",
     "hook-not-found-error",
+    "hook-conflict-error",
     "step-not-registered-error",
     "workflow-not-registered-error",
     "workflow-run-not-found-error",
     "workflow-run-failed-error",
     "workflow-run-cancelled-error",
+    "workflow-run-not-completed-error",
+    "workflow-runtime-error",
     "workflow-world-error",
     "throttle-error",
     "entity-conflict-error",
+    "precondition-failed-error",
     "run-expired-error",
+    "run-not-supported-error",
     "too-early-error"
   ]
 }

package/docs/api-reference/workflow-errors/precondition-failed-error.mdx

@@ -0,0 +1,68 @@
+---
+title: PreconditionFailedError
+description: World implementations throw this error when they reject an event creation because the client's event-log snapshot is stale.
+type: reference
+summary: Catch PreconditionFailedError when a World rejects an event creation made from a stale event-log snapshot.
+related:
+  - /docs/api-reference/workflow-errors/workflow-world-error
+  - /docs/api-reference/workflow-errors/entity-conflict-error
+---
+
+World implementations throw `PreconditionFailedError` when they reject an event creation because the client's event-log snapshot is stale: the log already held more events than the position the creation named. It corresponds to HTTP 412 Precondition Failed semantics.
+
+No World in this repository throws it. A stale replay does not need to be refused: its log is a prefix rather than a prefix with a hole in it, replay is deterministic on a prefix, and the write it makes next comes back carrying the events it was pushed past (see [Stale reads](/docs/configuration/runtime-tuning#stale-reads-and-why-nothing-has-to-be-rejected)). The error and the runtime's handling of it remain for a World that would rather refuse than report. Such a World allocates positions somewhere other than the commit, so it cannot report a gap reliably. Event creations that carry no position are never rejected with it.
+
+A World rejects only on evidence and accepts the creation whenever it cannot decide. This error always means the snapshot was stale, but not receiving it does not prove the snapshot was current.
+
+<Callout>
+The Workflow runtime handles this error by restarting the replay in the same invocation from a corrected event log. It re-invokes the run for a fresh replay only after spending its in-process restart budget. It never retries the rejected creation as-is because a replay working from a corrected log derives different events. You will only encounter it when interacting with World storage APIs directly.
+</Callout>
+
+A World may attach the events the client was missing to the rejection as `details`, which lets the runtime restart without re-reading the event log. This is optional, and the runtime falls back to a full reload when the details are absent or unusable.
+
+```typescript lineNumbers
+import { PreconditionFailedError } from "workflow/errors"
+declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
+declare const runId: string; // @setup
+declare const event: any; // @setup
+
+try {
+  await world.events.create(runId, event);
+} catch (error) {
+  if (PreconditionFailedError.is(error)) { // [!code highlight]
+    console.log("Snapshot is stale; reload the event log and retry");
+  }
+}
+```
+
+## API signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface PreconditionFailedError {
+  /** Delay in seconds before the operation should be retried. Present when the server sends a Retry-After header. */
+  retryAfter?: number;
+  /** Optional rejection payload. A world may put the events the client was missing here, as \`{ events, cursor }\`, so the runtime can restart its replay without re-reading the event log. */
+  details?: unknown;
+  /** The error message. */
+  message: string;
+}
+export default PreconditionFailedError;`}
+/>
+
+### Static methods
+
+#### `PreconditionFailedError.is(value)`
+
+Type-safe check for `PreconditionFailedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { PreconditionFailedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (PreconditionFailedError.is(error)) {
+  // error is typed as PreconditionFailedError
+}
+```

package/docs/api-reference/workflow-errors/run-expired-error.mdx

@@ -29,7 +29,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -42,7 +42,7 @@ interface RunExpiredError {
 export default RunExpiredError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `RunExpiredError.is(value)`
 

package/docs/api-reference/workflow-errors/run-not-supported-error.mdx

@@ -0,0 +1,58 @@
+---
+title: RunNotSupportedError
+description: Thrown when a workflow run requires a newer workflow spec version than the installed SDK supports.
+type: reference
+summary: Catch RunNotSupportedError when stored run data requires a newer workflow package version.
+related:
+  - /docs/foundations/versioning
+---
+
+`RunNotSupportedError` is thrown when reading a workflow run whose data was written with a newer workflow spec version than the running SDK supports. This typically means the run was created by a newer version of the `workflow` package. Upgrade the package to process it.
+
+```typescript lineNumbers
+import { RunNotSupportedError } from "workflow/errors"
+declare function readRun(runId: string): Promise<unknown>; // @setup
+declare const runId: string; // @setup
+
+try {
+  await readRun(runId);
+} catch (error) {
+  if (RunNotSupportedError.is(error)) { // [!code highlight]
+    console.error(
+      `Run requires spec v${error.runSpecVersion}, world supports v${error.worldSpecVersion}`
+    );
+  }
+}
+```
+
+## API signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface RunNotSupportedError {
+  /** The spec version the run's stored data requires. */
+  runSpecVersion: number;
+  /** The spec version the current World supports. */
+  worldSpecVersion: number;
+  /** The error message. */
+  message: string;
+}
+export default RunNotSupportedError;`}
+/>
+
+### Static methods
+
+#### `RunNotSupportedError.is(value)`
+
+Type-safe check for `RunNotSupportedError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
+
+```typescript
+import { RunNotSupportedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (RunNotSupportedError.is(error)) {
+  // error is typed as RunNotSupportedError
+}
+```

package/docs/api-reference/workflow-errors/step-not-registered-error.mdx

@@ -8,7 +8,7 @@ related:
   - /docs/api-reference/workflow-errors/workflow-not-registered-error
 ---
 
-`StepNotRegisteredError` is thrown when the runtime tries to execute a step function that is not registered in the current deployment. This is an infrastructure error — not a user code error. It typically indicates a build or bundling issue that caused the step to not be included in the deployment.
+`StepNotRegisteredError` is thrown when the runtime tries to execute a step function that is not registered in the current deployment. This is an infrastructure error, not a user code error. It typically indicates a build or bundling issue that caused the step to not be included in the deployment.
 
 When this error occurs, the step fails (like a `FatalError`) and control is passed back to the workflow function, which can handle the failure gracefully.
 
@@ -21,7 +21,7 @@ if (StepNotRegisteredError.is(error)) { // [!code highlight]
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -36,14 +36,14 @@ interface StepNotRegisteredError {
 export default StepNotRegisteredError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `StepNotRegisteredError.is(value)`
 
-Type-safe check for `StepNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `StepNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 <Callout>
-The `.is()` method works in server-side Node.js code (API routes, middleware, hooks). Inside `"use workflow"` functions, step errors arrive deserialized from the event log and won't be actual `StepNotRegisteredError` instances — use `error.message` matching instead. See the [troubleshooting page](/docs/errors/step-not-registered) for workflow-side error handling examples.
+The `.is()` method works in server-side Node.js code (API routes, middleware, hooks). Inside `"use workflow"` functions, step errors arrive deserialized from the event log and won't be actual `StepNotRegisteredError` instances. Use `error.message` matching instead. See the [troubleshooting page](/docs/errors/step-not-registered) for workflow-side error handling examples.
 </Callout>
 
 ```typescript

package/docs/api-reference/workflow-errors/throttle-error.mdx

@@ -31,7 +31,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -46,7 +46,7 @@ interface ThrottleError {
 export default ThrottleError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `ThrottleError.is(value)`
 

package/docs/api-reference/workflow-errors/too-early-error.mdx

@@ -31,7 +31,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -46,7 +46,7 @@ interface TooEarlyError {
 export default TooEarlyError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `TooEarlyError.is(value)`
 

package/docs/api-reference/workflow-errors/workflow-error.mdx

@@ -0,0 +1,52 @@
+---
+title: WorkflowError
+description: Base class for all workflow error types.
+type: reference
+summary: All errors thrown by the Workflow SDK extend WorkflowError.
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+`WorkflowError` is the base class that all Workflow SDK error types extend, such as [`WorkflowRunFailedError`](/docs/api-reference/workflow-errors/workflow-run-failed-error) and [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error). It extends `Error` with an optional `cause` and, for some subclasses, a link to the relevant error documentation appended to the message.
+
+```typescript lineNumbers
+import { WorkflowError } from "workflow/errors"
+
+const error = new WorkflowError("something went wrong", {
+  cause: new Error("underlying cause"),
+});
+```
+
+## API signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowError {
+  /** The error message. */
+  message: string;
+  /** The underlying cause, when provided. */
+  cause?: unknown;
+}
+export default WorkflowError;`}
+/>
+
+### Static methods
+
+#### `WorkflowError.is(value)`
+
+Type-safe check for `WorkflowError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
+
+<Callout type="warn">
+  `WorkflowError.is()` matches only direct `WorkflowError` instances, not subclasses, which override the error name it checks. To handle a specific error type, use that subclass's own `.is()` method (e.g. `WorkflowRunFailedError.is(error)`).
+</Callout>
+
+```typescript
+import { WorkflowError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowError.is(error)) {
+  // error is typed as WorkflowError
+}
+```

package/docs/api-reference/workflow-errors/workflow-not-registered-error.mdx

@@ -8,7 +8,7 @@ related:
   - /docs/api-reference/workflow-errors/step-not-registered-error
 ---
 
-`WorkflowNotRegisteredError` is thrown when the runtime tries to execute a workflow function that is not registered in the current deployment. This is an infrastructure error — not a user code error. It typically means a run was started against a deployment that does not have this workflow (e.g., the workflow was renamed or moved), or there was a build/bundling issue.
+`WorkflowNotRegisteredError` is thrown when the runtime tries to execute a workflow function that is not registered in the current deployment. This is an infrastructure error, not a user code error. It typically means a run was started against a deployment that does not have this workflow (e.g., the workflow was renamed or moved), or there was a build/bundling issue.
 
 When this error occurs, the run fails with a `RUNTIME_ERROR` error code.
 
@@ -21,7 +21,7 @@ if (WorkflowNotRegisteredError.is(error)) { // [!code highlight]
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -36,14 +36,14 @@ interface WorkflowNotRegisteredError {
 export default WorkflowNotRegisteredError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `WorkflowNotRegisteredError.is(value)`
 
-Type-safe check for `WorkflowNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `WorkflowNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 <Callout>
-The `.is()` method works in server-side Node.js code (API routes, middleware). When checking the error from `run.returnValue`, use `WorkflowRunFailedError.is()` and inspect `error.cause` — the underlying error is deserialized from the event log.
+The `.is()` method works in server-side Node.js code (API routes, middleware). When checking the error from `run.returnValue`, use `WorkflowRunFailedError.is()` and inspect `error.cause`: the underlying error is deserialized from the event log.
 </Callout>
 
 ```typescript
@@ -54,4 +54,3 @@ if (WorkflowNotRegisteredError.is(error)) {
   // error is typed as WorkflowNotRegisteredError
 }
 ```
-

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

@@ -1,14 +1,14 @@
 ---
 title: WorkflowRunCancelledError
-description: Thrown when awaiting the return value of a cancelled workflow run.
+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 cancelled.
+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 cancelled via `run.cancel()`. Cancelled runs do not produce a return value.
+`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`.
 
@@ -25,14 +25,14 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
 <TSDoc
 definition={`
 interface WorkflowRunCancelledError {
-  /** The ID of the cancelled run. */
+  /** The ID of the canceled run. */
   runId: string;
   /** The error message. */
   message: string;
@@ -40,7 +40,7 @@ interface WorkflowRunCancelledError {
 export default WorkflowRunCancelledError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `WorkflowRunCancelledError.is(value)`
 

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

@@ -11,7 +11,7 @@ related:
 
 `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.
+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.
 
 ```typescript lineNumbers
 import { WorkflowRunFailedError } from "workflow/errors"
@@ -31,7 +31,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -45,7 +45,7 @@ interface WorkflowRunFailedError {
    * 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 — narrow with \`instanceof Error\` before accessing fields.
+   * be thrown, so narrow with \`instanceof Error\` before accessing fields.
    */
   cause: unknown;
   /** The high-level error category (e.g. \`USER_ERROR\`, \`RUNTIME_ERROR\`). */
@@ -56,11 +56,11 @@ interface WorkflowRunFailedError {
 export default WorkflowRunFailedError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `WorkflowRunFailedError.is(value)`
 
-Type-safe check for `WorkflowRunFailedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+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"

package/docs/api-reference/workflow-errors/workflow-run-not-completed-error.mdx

@@ -0,0 +1,58 @@
+---
+title: WorkflowRunNotCompletedError
+description: Thrown when requesting the result of a workflow run that has not completed yet.
+type: reference
+summary: Catch WorkflowRunNotCompletedError when reading the return value of a run that is still pending or running.
+related:
+  - /docs/api-reference/workflow-api/get-run
+---
+
+`WorkflowRunNotCompletedError` is thrown when requesting the result of a workflow run that has not completed yet. The run's current status (for example `pending` or `running`) is available on the error.
+
+[`run.returnValue()`](/docs/api-reference/workflow-api/get-run) handles this error internally (it polls until the run completes), so you will mainly encounter it when building custom polling logic on lower-level APIs.
+
+```typescript lineNumbers
+import { WorkflowRunNotCompletedError } from "workflow/errors"
+declare function readRunResult(runId: string): Promise<unknown>; // @setup
+declare const runId: string; // @setup
+
+try {
+  const result = await readRunResult(runId);
+} catch (error) {
+  if (WorkflowRunNotCompletedError.is(error)) { // [!code highlight]
+    console.log(`Run ${error.runId} is still ${error.status}`);
+  }
+}
+```
+
+## API signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRunNotCompletedError {
+  /** The workflow run ID. */
+  runId: string;
+  /** The run's status at the time of the error (e.g. "pending", "running"). */
+  status: string;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowRunNotCompletedError;`}
+/>
+
+### Static methods
+
+#### `WorkflowRunNotCompletedError.is(value)`
+
+Type-safe check for `WorkflowRunNotCompletedError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
+
+```typescript
+import { WorkflowRunNotCompletedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRunNotCompletedError.is(error)) {
+  // error is typed as WorkflowRunNotCompletedError
+}
+```

package/docs/api-reference/workflow-errors/workflow-run-not-found-error.mdx

@@ -10,7 +10,7 @@ related:
 
 `WorkflowRunNotFoundError` is thrown when performing operations on a workflow run that does not exist. This includes calling methods like `run.status`, `run.cancel()`, or awaiting `run.returnValue` on a run whose ID does not match any known workflow run.
 
-Note that `getRun(id)` itself is synchronous and will not throw — the error is raised when subsequent operations on the run object discover the run is missing.
+`getRun(id)` itself is synchronous and will not throw. Subsequent operations on the run object raise the error when they discover the run is missing.
 
 ```typescript lineNumbers
 import { WorkflowRunNotFoundError } from "workflow/errors"
@@ -25,7 +25,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -40,11 +40,11 @@ interface WorkflowRunNotFoundError {
 export default WorkflowRunNotFoundError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `WorkflowRunNotFoundError.is(value)`
 
-Type-safe check for `WorkflowRunNotFoundError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `WorkflowRunNotFoundError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 ```typescript
 import { WorkflowRunNotFoundError } from "workflow/errors"

package/docs/api-reference/workflow-errors/workflow-runtime-error.mdx

@@ -0,0 +1,58 @@
+---
+title: WorkflowRuntimeError
+description: Thrown when the workflow runtime encounters an execution error, such as serialization failures or timeouts.
+type: reference
+summary: Catch WorkflowRuntimeError for runtime-level failures like unserializable values or workflow timeouts.
+related:
+  - /docs/foundations/serialization
+  - /docs/foundations/errors-and-retries
+---
+
+`WorkflowRuntimeError` is thrown when the workflow runtime encounters an error executing a workflow. Common causes include:
+
+- Values crossing the workflow/step boundary that cannot be serialized
+- Workflow execution timeouts
+- Invalid runtime state, such as misconfigured streams
+
+```typescript lineNumbers
+import { WorkflowRuntimeError } from "workflow/errors"
+declare function runWorkflowOperation(): Promise<void>; // @setup
+
+try {
+  await runWorkflowOperation();
+} catch (error) {
+  if (WorkflowRuntimeError.is(error)) { // [!code highlight]
+    console.error("Workflow runtime error:", error.message);
+  }
+}
+```
+
+## API signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRuntimeError {
+  /** The error message. */
+  message: string;
+  /** The underlying cause, when provided. */
+  cause?: unknown;
+}
+export default WorkflowRuntimeError;`}
+/>
+
+### Static methods
+
+#### `WorkflowRuntimeError.is(value)`
+
+Type-safe check for `WorkflowRuntimeError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRuntimeError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRuntimeError.is(error)) {
+  // error is typed as WorkflowRuntimeError
+}
+```