workflow 5.0.0-beta.5 → 5.0.0-beta.51

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

@@ -0,0 +1,77 @@
+---
+title: runtime-decryption-failed
+description: The SDK's built-in AES-GCM encryption layer failed to encrypt or decrypt a workflow payload.
+type: troubleshooting
+summary: Resolve runtime decryption failures caused by ciphertext corruption, key mismatch, or malformed envelopes.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+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, 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
+
+```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 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)
+
+## 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.
+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
+
+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
+
+The underlying issue may have already been identified and fixed:
+
+```bash
+npm install workflow@latest
+```
+
+### 2. Retry the failed run
+
+Since this is a fatal error, the run is automatically marked as `failed`. You can re-run it using the **Re-run** button in the Workflow Dashboard.
+
+### 3. Report the issue
+
+If the error persists after upgrading, please [open an issue on GitHub](https://github.com/vercel/workflow/issues/new) so we can investigate. Include:
+
+- The version of the `workflow` package you are using
+- The run ID(s) of the affected workflow run(s)
+- 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
+
+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`.
+
+To handle this programmatically from outside the workflow, check the run status:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+const run = getRun("wrun_abc123");
+const status = await run.status;
+if (status === "failed") {
+  console.error("Run failed");
+}
+```

package/docs/errors/serialization-failed.mdx

@@ -9,11 +9,15 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="Fix Workflow serialization errors. Find the failing `start()` call, workflow argument, step return value, hook payload, or stream chunk. Replace non-serializable values such as class instances, functions, SDK clients, Response/Request objects, streams, database connections, Dates that need custom handling, Maps/Sets, or circular objects with plain JSON-compatible data, IDs, strings, numbers, booleans, arrays, and objects. Recreate runtime-only clients or objects inside `&quot;use step&quot;` helpers instead of passing them through the workflow log. For external resources, pass a stable ID or URL and load the resource inside the step. Add a test or local route call that serializes the same input/output path successfully."
+/>
+
 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).
 ```
@@ -25,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:
 
@@ -34,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
@@ -68,7 +100,7 @@ async function processStep(config: { shouldLog: boolean }) {
 }
 ```
 
-### Class Instances
+### Class instances
 
 ```typescript lineNumbers
 class User {
@@ -107,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
@@ -119,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

@@ -11,19 +11,23 @@ related:
   - /docs/api-reference/workflow-next/with-workflow
 ---
 
+<CopyPrompt
+  text="Fix `start()` receiving an invalid workflow function. Find the function passed to `start()` from `workflow/api`. Ensure the target function is directly imported, exported from its workflow file, and contains the literal `&quot;use workflow&quot;` directive at the top of the function body. Do not pass wrapper callbacks like `start(async () => workflowFn())`; call `start(workflowFn, [args])`. Verify the framework integration is configured (`withWorkflow()` in Next.js, `workflow()`/`workflowPlugin()` in Vite/Astro/SvelteKit, `workflow/nitro`, `workflow/nuxt`, or `@workflow/nest` as appropriate) and that the workflow file is inside a transformed directory. Add a local route/test that calls `start(workflowFn, args)` and confirms a run is created."
+/>
+
 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

@@ -0,0 +1,23 @@
+---
+title: Step executed multiple times
+description: A step ran more than once because its function invocation crashed before it could report a result.
+type: troubleshooting
+summary: Diagnose duplicate step_started events caused by function timeouts, OOMs, or network issues.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/foundations/errors-and-retries
+---
+
+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
+
+- **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
+
+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

@@ -4,7 +4,7 @@ description: A step function is not registered in the current deployment.
 type: troubleshooting
 summary: Resolve step not registered errors caused by build issues.
 prerequisites:
-  - /docs/foundations/steps
+  - /docs/foundations/workflows-and-steps
 related:
   - /docs/errors/workflow-not-registered
   - /docs/api-reference/workflow-errors/step-not-registered-error
@@ -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

@@ -9,21 +9,25 @@ related:
   - /docs/api-reference/workflow/sleep
 ---
 
+<CopyPrompt
+  text="Fix timer usage inside workflow functions. Search `&quot;use workflow&quot;` functions for `setTimeout`, `setInterval`, `timers/promises`, polling loops, or `AbortSignal.timeout()`. Replace workflow delays with `await sleep(&quot;5s&quot;)`, `await sleep(&quot;24h&quot;)`, or `await sleep(date)` from `workflow`. For polling, use a workflow loop that calls a `&quot;use step&quot;` helper to check external state and then `await sleep(...)` between attempts. If a step itself needs a short in-process delay, keep that timer inside the `&quot;use step&quot;` function only. Verify the workflow can replay and resume after the durable sleep."
+/>
+
 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.
 
@@ -55,7 +59,7 @@ export async function delayedWorkflow() {
 }
 ```
 
-## Unavailable Functions
+## Unavailable functions
 
 These timing functions cannot be used in workflow functions:
 
@@ -66,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:
 
@@ -98,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

@@ -9,30 +9,34 @@ related:
   - /docs/api-reference/workflow/create-webhook
 ---
 
+<CopyPrompt
+  text="Fix webhook-response-not-sent errors. Find `createWebhook({ respondWith: &quot;manual&quot; })` usage. In the workflow, await the webhook request and pass the `RequestWithResponse` into a `&quot;use step&quot;` helper for validation and side effects. In every success, validation failure, catch, and early-return branch, call `await request.respondWith(new Response(...))` or `await request.respondWith(Response.json(...))` exactly once before the webhook completes. If manual control is not needed, remove `respondWith: &quot;manual&quot;` or use a static `Response` option. Add tests or local webhook calls for success, invalid input, and thrown-error paths."
+/>
+
 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",
   });
 
@@ -55,7 +59,7 @@ import { createWebhook } from "workflow";
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "manual",
   });
 
@@ -70,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",
   });
 
@@ -100,7 +104,7 @@ import { createWebhook } from "workflow";
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "manual",
   });
 
@@ -115,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",
   });
 
@@ -145,7 +149,7 @@ import { createWebhook } from "workflow";
 export async function webhookWorkflow() {
   "use workflow";
 
-  const webhook = await createWebhook({
+  const webhook = createWebhook({
     respondWith: "manual",
   });
 
@@ -164,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:
 
@@ -175,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
@@ -185,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.