workflow 5.0.0-beta.43 → 5.0.0-beta.44

package/docs/errors/node-js-module-in-workflow.mdx

@@ -15,19 +15,19 @@ related:
 
 This error occurs when you try to import or use Node.js core modules (like `fs`, `http`, `crypto`, `path`, etc.) directly inside a workflow function.
 
-## Error Message
+## Error message
 
-```
+```text
 Cannot use Node.js module "fs" in workflow functions. Move this module to a step function.
 ```
 
-## Why This Happens
+## Why this happens
 
 Workflow functions run in a sandboxed environment without full Node.js runtime access. This restriction is important for maintaining **determinism** - the ability to replay workflows exactly and resume from where they left off after suspensions or failures.
 
 Node.js modules have side effects and non-deterministic behavior that could break workflow replay guarantees.
 
-## Quick Fix
+## Quick fix
 
 Move any code using Node.js modules to a step function. Step functions have full Node.js runtime access.
 
@@ -68,7 +68,7 @@ async function read(filePath: string) {
 }
 ```
 
-## Common Node.js Modules
+## Common Node.js modules
 
 These common Node.js core modules cannot be used in workflow functions:
 

package/docs/errors/replay-divergence.mdx

@@ -14,7 +14,7 @@ A replay divergence occurs when one invocation of a workflow cannot consume the
 
 This is an SDK/runtime signal, not an error thrown by your workflow code. It is not catchable inside a workflow function.
 
-## Automatic Recovery
+## Automatic recovery
 
 A single divergent replay does not prove that persisted history is corrupted. For example, asynchronous delivery ordering may cause one invocation to follow the wrong side of a race while another replay can follow the recorded history correctly.
 
@@ -22,6 +22,6 @@ The runtime automatically queues another replay when an invocation reports `REPL
 
 If recovery replays continue to diverge after the recovery budget is exhausted, the runtime marks the run as failed with `CORRUPTED_EVENT_LOG` and records the latest divergent event for diagnosis.
 
-## What To Do
+## What to do
 
 Most replay divergence signals recover without action. If a run ultimately fails with `CORRUPTED_EVENT_LOG`, update to the latest `workflow` package and report the run ID and error details if the failure persists.

package/docs/errors/runtime-decryption-failed.mdx

@@ -11,33 +11,33 @@ related:
 
 This error occurs when the Workflow SDK's built-in AES-GCM encryption layer fails while encrypting or decrypting a workflow payload. The SDK encrypts step inputs, step outputs, hook payloads, and other event-log data with a per-run AES-256 key whenever encryption is configured for the deployment.
 
-This is an **internal SDK failure** — your workflow code never invokes the encryption primitives directly. When this surfaces, it means the ciphertext, nonce, or auth tag the SDK tried to verify is not the bytes that were originally produced. The run is failed with the `RUNTIME_ERROR` classification.
+This is an **internal SDK failure**: your workflow code never invokes the encryption primitives directly. When this surfaces, the ciphertext, nonce, or authentication tag the SDK tried to verify does not match the bytes that were originally produced. The run fails with the `RUNTIME_ERROR` classification.
 
-## Error Message
+## Error message
 
-```
+```text
 AES-256-GCM decryption failed: The operation failed for an operation-specific reason
 ```
 
-The underlying cause is a native Web Crypto [`OperationError`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException#operationerror) — most commonly raised by `AESCipherJob.onDone` in Node's `node:internal/crypto/util` module when the GCM authentication tag does not verify.
+The underlying cause is a native Web Crypto [`OperationError`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException#operationerror), most commonly raised by `AESCipherJob.onDone` in Node's `node:internal/crypto/util` module when the GCM authentication tag does not verify.
 
 The thrown `RuntimeDecryptionError` carries a small `context` object with diagnostic fields to help triangulate the source:
 
-- `operation` — `'encrypt'` or `'decrypt'`
-- `byteLength` — total byte length of the payload at the failure site
-- `formatPrefix` — the first 4 bytes of the input (`'encr'` for a well-formed encrypted envelope, otherwise a hex dump)
+- `operation`: `'encrypt'` or `'decrypt'`
+- `byteLength`: total byte length of the payload at the failure site
+- `formatPrefix`: the first 4 bytes of the input (`'encr'` for a well-formed encrypted envelope, otherwise a hex dump)
 
-## Why This Happens
+## Why this happens
 
 Common causes, in rough order of likelihood:
 
 1. **Ciphertext mutation or truncation in transit.** The encrypted payload reached the SDK with bytes that differ from what storage holds. Possible sources include a truncated HTTP response from a workflow-server ref endpoint, an edge-cache miss returning a partial 200, or a proxy drop during streaming. A truncated body whose first 4 bytes happen to still spell `encr` produces the exact "auth tag mismatch" symptom.
-2. **Key resolution mismatch.** The key used to decrypt is not the key that was used to encrypt — e.g. the run's `deploymentId` was not threaded through key resolution and the SDK fell back to the wrong deployment's key material.
+2. **Key resolution mismatch.** The key used to decrypt is not the key that was used to encrypt, e.g. the run's `deploymentId` was not threaded through key resolution and the SDK fell back to the wrong deployment's key material.
 3. **Malformed encrypted envelope.** The envelope is too short to contain the GCM nonce (12 bytes) and auth tag (16 bytes), so decryption is rejected before it begins.
 
-## What To Do
+## What to do
 
-This error indicates an SDK or infrastructure problem — not a bug in your workflow code. Your workflow code does not need to change.
+This error indicates an SDK or infrastructure problem, not a bug in your workflow code. Your workflow code does not need to change.
 
 ### 1. Upgrade to the latest `workflow` package
 
@@ -60,7 +60,7 @@ If the error persists after upgrading, please [open an issue on GitHub](https://
 - The full error message, including the `context` fields (`operation`, `byteLength`, `formatPrefix`)
 - Whether the affected workflows make heavy use of large step inputs/outputs (which may indicate the failure is on the lazy-loaded ref read path)
 
-## This Error Cannot Be Caught
+## This error cannot be caught
 
 Like other `WorkflowRuntimeError` subclasses, a runtime decryption failure is **not catchable** inside your workflow function. The runtime cannot safely continue executing user code when an event-log payload can't be verified, so the entire run fails immediately and is marked as `failed`.
 

package/docs/errors/serialization-failed.mdx

@@ -15,9 +15,9 @@ related:
 
 This error occurs when you try to pass non-serializable data between execution boundaries in your workflow. All data passed between workflow functions, step functions, and the workflow runtime must be serializable to persist in the event log.
 
-## Error Message
+## Error message
 
-```
+```text
 Failed to serialize workflow arguments. Ensure you're passing serializable types
 (plain objects, arrays, primitives, Date, RegExp, Map, Set).
 ```
@@ -29,7 +29,35 @@ This error can appear when:
 - Serializing step arguments
 - Serializing step return values
 
-## Why This Happens
+## Where the error surfaces
+
+Where you observe the failure depends on which boundary it crosses:
+
+- **Workflow arguments**: `start()` throws synchronously in your application code.
+- **Step arguments and step return values**: the *step* fails with the `SerializationError`, exactly like a step whose body threw a fatal error: no retries (the failure is deterministic), and a `try/catch` around the step call in your workflow code observes it. The step's recorded input shows `[input unavailable: step argument serialization failed]` when the arguments were the unserializable part.
+- **Workflow return values**: the workflow body has already returned, so nothing can catch it; the run fails.
+
+```typescript lineNumbers
+async function stepWithBadArguments(value: unknown) {
+  "use step";
+  return value;
+}
+
+export async function processWorkflow(someValue: unknown) {
+  "use workflow";
+
+  try {
+    await stepWithBadArguments(someValue);
+  } catch (err) {
+    // err.name === "SerializationError"
+    // "Failed to serialize step arguments at path ..."
+  }
+}
+```
+
+Uncaught, the error propagates out of the workflow body and the run fails immediately with the error code `USER_ERROR`; it does not retry.
+
+## Why this happens
 
 Workflows persist their state using an event log. Every value that crosses execution boundaries must be:
 
@@ -38,9 +66,9 @@ Workflows persist their state using an event log. Every value that crosses execu
 
 Functions, class instances, symbols, and other non-serializable types cannot be properly reconstructed after serialization, which would break workflow replay.
 
-## Common Causes
+## Common causes
 
-### Passing Functions
+### Passing functions
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript lineNumbers
@@ -72,7 +100,7 @@ async function processStep(config: { shouldLog: boolean }) {
 }
 ```
 
-### Class Instances
+### Class instances
 
 ```typescript lineNumbers
 class User {
@@ -111,11 +139,11 @@ async function greetStep(userData: { name: string }) {
 }
 ```
 
-## Supported Serializable Types
+## Supported serializable types
 
 Workflow SDK supports these types across execution boundaries:
 
-### Standard JSON Types
+### Standard JSON types
 
 - `string`, `number`, `boolean`, `null`
 - Arrays of serializable values
@@ -123,10 +151,10 @@ Workflow SDK supports these types across execution boundaries:
 
 To learn more about supported types, see the [Serialization](/docs/foundations/serialization) section.
 
-## Debugging Serialization Issues
+## Debugging serialization issues
 
 To identify what's causing serialization to fail:
 
-1. **Check the error stack trace** - it often shows which property failed
-2. **Simplify your data** - temporarily pass smaller objects to isolate the issue
-3. **Ensure you are using supported data types** - see the [Serialization](/docs/foundations/serialization) section for more details
+1. **Check the error stack trace**: It often shows which property failed.
+2. **Simplify your data**: Temporarily pass smaller objects to isolate the issue.
+3. **Use supported data types**: See [Serialization](/docs/foundations/serialization) for details.

package/docs/errors/start-invalid-workflow-function.mdx

@@ -17,17 +17,17 @@ related:
 
 This error occurs when `start()` receives a function that does not have Workflow SDK's generated workflow metadata. In practice, that usually means the function is missing `"use workflow"` or the file was never transformed by your framework integration.
 
-## Error Message
+## Error message
 
-```
+```text
 'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.
 ```
 
-## Why This Happens
+## Why this happens
 
-`start()` expects an imported workflow function, not just any async function. During compilation, Workflow SDK transforms files that contain `"use workflow"` and attaches generated metadata such as the workflow ID. If that transform never runs, or if you pass a wrapper function instead of the transformed export, `start()` cannot identify what to enqueue and throws this error.
+`start()` expects an imported workflow function rather than any async function. During compilation, Workflow SDK transforms files that contain `"use workflow"` and attaches generated metadata such as the workflow ID. If that transform never runs, or if you pass a wrapper function instead of the transformed export, `start()` cannot identify what to enqueue and throws this error.
 
-## Common Causes
+## Common causes
 
 ### Missing `"use workflow"`
 

package/docs/errors/step-executed-multiple-times.mdx

@@ -12,12 +12,12 @@ related:
 
 There may be cases where you see multiple `step_started` events for the same step in a workflow run. This happens if the function invocation executing the step crashes unexpectedly, and the step can not report the error. The step will be re-tried according to your retry policy in this case, but no error will be visible in the [Observability UI](/docs/observability).
 
-## Common Causes
+## Common causes
 
 - **Function timeouts**: if your step code runs longer than the configured maximum function duration, it will be killed. Compare the gap between the `step_started` events to your configured function duration to be sure.
 - **Out of memory (OOM)**: if your step code loads enough data into memory, especially if the step is invoked concurrently, the function invocation might run out of memory. You can see your function's peak memory use by going to the [Observability Query page](https://vercel.com/docs/observability) and showing the **Function Invocation Peak Memory** metric, then filtering down the **Route** to `/.well-known/workflow` endpoints.
 - **Network issues**: persistent firewall, network stability, and related issues might prevent your function from reporting results or errors. This should be temporary.
 
-## Getting Help
+## Getting help
 
 If you consistently see multiple `step_started` events and have ruled out function timeouts, OOMs, and firewall issues, please [contact support](https://vercel.com/help).

package/docs/errors/step-not-registered.mdx

@@ -12,21 +12,21 @@ related:
 
 This error occurs when the Workflow runtime tries to execute a step function that is not registered in the current deployment. When this happens, the step fails (like a `FatalError`) and control is passed back to the workflow function, which can optionally handle the failure.
 
-## Error Message
+## Error message
 
-```
+```text
 Step "<stepName>" is not registered in the current deployment.
 This usually indicates a build or bundling issue that caused the step
 to not be included in the deployment.
 ```
 
-## Why This Happens
+## Why this happens
 
 Workflow runs are pegged to a specific deployment, so this error is not caused by newer deployments overriding the running code. Instead, it means the step function was not included in the deployment's workflow bundle at build time.
 
 This is an **infrastructure error**, not a user code error.
 
-## Common Causes
+## Common causes
 
 ### Build tooling issue
 
@@ -40,7 +40,7 @@ Something went wrong during the build process that caused the step function to n
 
 The step function was deleted or its `"use step"` directive was removed, but the workflow still references it. Ensure all steps referenced by your workflow are present in the codebase.
 
-## How to Resolve
+## How to resolve
 
 1. **Check your build logs:** Look for errors or warnings related to workflow bundling. Ensure the step file contains a valid `"use step"` directive and is properly exported.
 

package/docs/errors/timeout-in-workflow.mdx

@@ -15,19 +15,19 @@ related:
 
 This error occurs when you try to use `setTimeout()`, `setInterval()`, or related timing functions directly inside a workflow function.
 
-## Error Message
+## Error message
 
-```
+```text
 Timeout functions like "setTimeout" and "setInterval" are not supported in workflow functions. Use the "sleep" function from "workflow" for time-based delays.
 ```
 
-## Why This Happens
+## Why this happens
 
 Workflow functions run in a sandboxed environment where timing functions like `setTimeout()` and `setInterval()` are not available. These functions rely on asynchronous scheduling that would break the **deterministic replay** guarantees that workflows depend on.
 
 When a workflow suspends and later resumes, it replays from the event log. If timing functions were allowed, the replay would produce different results than the original execution.
 
-## Quick Fix
+## Quick fix
 
 Use the `sleep` function from the `workflow` package for time-based delays. Unlike `setTimeout()`, `sleep` is tracked in the event log and replays correctly.
 
@@ -59,7 +59,7 @@ export async function delayedWorkflow() {
 }
 ```
 
-## Unavailable Functions
+## Unavailable functions
 
 These timing functions cannot be used in workflow functions:
 
@@ -70,9 +70,9 @@ These timing functions cannot be used in workflow functions:
 - `clearInterval()`
 - `clearImmediate()`
 
-## Common Scenarios
+## Common scenarios
 
-### Polling with Delays
+### Polling with delays
 
 If you need to poll an external service with delays between requests:
 
@@ -102,7 +102,7 @@ async function checkStatus() {
 }
 ```
 
-### Scheduled Delays
+### Scheduled delays
 
 For workflows that need to wait for a specific duration:
 

package/docs/errors/webhook-invalid-respond-with-value.mdx

@@ -11,13 +11,13 @@ related:
 
 This error occurs when you provide an invalid value for the `respondWith` option when creating a webhook. The `respondWith` option must be either `"manual"` or a `Response` object.
 
-## Error Message
+## Error message
 
-```
+```text
 Invalid `respondWith` value: [value]
 ```
 
-## Why This Happens
+## Why this happens
 
 When creating a webhook with `createWebhook()`, you can specify how the webhook should respond to incoming HTTP requests using the `respondWith` option. This option only accepts specific values:
 
@@ -25,16 +25,16 @@ When creating a webhook with `createWebhook()`, you can specify how the webhook
 2. A `Response` object - A pre-defined response to send immediately
 3. `undefined` (default) - Returns a `202 Accepted` response
 
-## Common Causes
+## Common causes
 
-### Using an Invalid String Value
+### Using an invalid string value
 
 ```typescript lineNumbers
 // Error - invalid string value
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "automatic", // Error! // [!code highlight]
   });
 }
@@ -49,7 +49,7 @@ import { createWebhook } from "workflow";
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "manual", // [!code highlight]
   });
 
@@ -60,14 +60,14 @@ export async function webhookWorkflow() {
 }
 ```
 
-### Using a Non-Response Object
+### Using a non-Response object
 
 ```typescript lineNumbers
 // Error - plain object instead of Response
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: { status: 200, body: "OK" }, // Error! // [!code highlight]
   });
 }
@@ -82,32 +82,32 @@ import { createWebhook } from "workflow";
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: new Response("OK", { status: 200 }), // [!code highlight]
   });
 }
 ```
 
-## Valid Usage Examples
+## Valid usage examples
 
-### Default Behavior (202 Response)
+### Default behavior (202 response)
 
 ```typescript lineNumbers
 import { createWebhook } from "workflow";
 
 // Returns 202 Accepted automatically
-const webhook = await createWebhook();
+const webhook = createWebhook();
 const request = await webhook;
 // No need to send a response
 ```
 
-### Manual Response
+### Manual response
 
 ```typescript lineNumbers
 import { createWebhook } from "workflow";
 
 // Manual response control
-const webhook = await createWebhook({
+const webhook = createWebhook({
   respondWith: "manual",
 });
 
@@ -125,13 +125,13 @@ await request.respondWith(
 );
 ```
 
-### Pre-defined Response
+### Pre-defined response
 
 ```typescript lineNumbers
 import { createWebhook } from "workflow";
 
 // Immediate response
-const webhook = await createWebhook({
+const webhook = createWebhook({
   respondWith: new Response("Request received", { status: 200 }),
 });
 
@@ -139,7 +139,7 @@ const request = await webhook;
 // Response already sent
 ```
 
-## Learn More
+## Learn more
 
 - [createWebhook() API Reference](/docs/api-reference/workflow/create-webhook)
 - [resumeWebhook() API Reference](/docs/api-reference/workflow-api/resume-webhook)

package/docs/errors/webhook-response-not-sent.mdx

@@ -15,28 +15,28 @@ related:
 
 This error occurs when a webhook is configured with `respondWith: "manual"` but the workflow does not send a response using `request.respondWith()` before the webhook execution completes.
 
-## Error Message
+## Error message
 
-```
+```text
 Workflow run did not send a response
 ```
 
-## Why This Happens
+## Why this happens
 
 When you create a webhook with `respondWith: "manual"`, you are responsible for calling `request.respondWith()` to send the HTTP response back to the caller. If the workflow execution completes without sending a response, this error will be thrown.
 
 The webhook infrastructure waits for a response to be sent, and if none is provided, it cannot complete the HTTP request properly.
 
-## Common Causes
+## Common causes
 
-### Forgetting to Call `request.respondWith()`
+### Forgetting to call `request.respondWith()`
 
 ```typescript lineNumbers
 // Error - no response sent
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "manual",
   });
 
@@ -59,7 +59,7 @@ import { createWebhook } from "workflow";
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "manual",
   });
 
@@ -74,14 +74,14 @@ export async function webhookWorkflow() {
 }
 ```
 
-### Conditional Response Logic
+### Conditional response logic
 
 ```typescript lineNumbers
 // Error - response only sent in some branches
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "manual",
   });
 
@@ -104,7 +104,7 @@ import { createWebhook } from "workflow";
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "manual",
   });
 
@@ -119,14 +119,14 @@ export async function webhookWorkflow() {
 }
 ```
 
-### Exception Before Response
+### Exception before response
 
 ```typescript lineNumbers
 // Error - exception thrown before response
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "manual",
   });
 
@@ -149,7 +149,7 @@ import { createWebhook } from "workflow";
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "manual",
   });
 
@@ -168,7 +168,7 @@ export async function webhookWorkflow() {
 }
 ```
 
-## Alternative: Use Default Response Mode
+## Alternative: Use default response mode
 
 If you don't need custom response control, consider using the default response mode which automatically returns a `202 Accepted` response:
 
@@ -179,7 +179,7 @@ import { createWebhook } from "workflow";
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook(); // [!code highlight]
+  const webhook = createWebhook(); // [!code highlight]
   const request = await webhook;
 
   // Process request asynchronously
@@ -189,7 +189,7 @@ export async function webhookWorkflow() {
 }
 ```
 
-## Learn More
+## Learn more
 
 - [createWebhook() API Reference](/docs/api-reference/workflow/create-webhook)
 - [resumeWebhook() API Reference](/docs/api-reference/workflow-api/resume-webhook)

package/docs/errors/workflow-not-registered.mdx

@@ -12,19 +12,19 @@ related:
 
 This error occurs when the Workflow runtime tries to execute a workflow function that is not registered in the current deployment. When this happens, the run fails with a `RUNTIME_ERROR` error code.
 
-## Error Message
+## Error message
 
-```
+```text
 Workflow "<workflowName>" is not registered in the current deployment.
 This usually means a run was started against a deployment that does not
 have this workflow, or there was a build/bundling issue.
 ```
 
-## Why This Happens
+## Why this happens
 
 This error means the deployment that received the workflow execution request does not have the specified workflow function in its bundle. This is an **infrastructure error**, not a user code error.
 
-## Common Causes
+## Common causes
 
 ### Run started against a deployment without the workflow
 
@@ -57,7 +57,7 @@ Something went wrong during the build process that caused the workflow function
 - The workflow function is not exported from the workflow file
 - An esbuild or SWC plugin error silently excluded the workflow
 
-## How to Resolve
+## How to resolve
 
 1. **If the workflow was renamed or moved:** Deploy with the workflow restored to its original name and location, then retry the run. Alternatively, start a new run using the updated workflow name against the current deployment.