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

package/docs/errors/hook-conflict.mdx

@@ -10,15 +10,19 @@ related:
   - /docs/api-reference/workflow/define-hook
 ---
 
+<CopyPrompt
+  text="Fix hook token conflicts. Find every `createHook({ token })` or typed hook creation site. If multiple waits can exist at the same time, include a unique stable discriminator in the token such as `${workflowRunId}:approval:${itemId}` or `${orderId}:${attempt}` instead of reusing one global token. If duplicate work should join an existing run, catch `HookConflictError` from `@workflow/errors`, read the conflicting run ID from the error/result if available, and use `getRun(runId)` plus `resumeHook()` from `workflow/api` to deliver the payload to the active run. Keep token generation deterministic across retries so replay does not create new hook identities. Verify two concurrent runs and a duplicate request no longer throw hook-conflict unexpectedly."
+/>
+
 This error occurs when you try to create a hook with a token that is already in use by another active workflow run. Hook tokens must be unique across all running workflows in your project.
 
-## Error Message
+## Error message
 
-```
+```text
 Hook token "<token>" is already in use by another workflow
 ```
 
-## Why This Happens
+## Why this happens
 
 Hooks use tokens to identify incoming webhook payloads. When you create a hook with `createHook({ token: "my-token" })`, the Workflow runtime reserves that token for your workflow run. If another workflow run is already using that token, a conflict occurs.
 
@@ -27,9 +31,9 @@ This typically happens when:
 1. **Two workflows start simultaneously** with the same hardcoded token
 2. **A previous workflow run is still waiting** for a hook when a new run tries to use the same token
 
-## Common Causes
+## Common causes
 
-### Hardcoded Token Values
+### Hardcoded token values
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript lineNumbers
@@ -57,7 +61,7 @@ export async function processPayment(orderId: string) {
 }
 ```
 
-### Omitting the Token (Auto-generated)
+### Omitting the token (auto-generated)
 
 The safest approach is to let the Workflow runtime generate a unique token automatically:
 
@@ -73,9 +77,9 @@ export async function processPayment() {
 }
 ```
 
-## Handling Hook Conflicts in Your Workflow
+## Handling hook conflicts
 
-When a hook conflict occurs, awaiting the hook will throw a `HookConflictError`. You can catch this error to handle the conflict gracefully:
+When a hook conflict occurs, awaiting the hook will throw a `HookConflictError`. The error exposes the token that conflicted and, for current worlds, the run ID that currently owns it. `conflictingRunId` remains optional for compatibility with older persisted events and world implementations, so guard it before delegating:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -93,26 +97,76 @@ export async function processPayment(orderId: string) {
     if (HookConflictError.is(error)) { // [!code highlight]
       // Another workflow is already processing this order
       console.log(`Conflicting token: ${error.token}`);
-      return { success: false, reason: "duplicate-processing" };
+      if (error.conflictingRunId) {
+        console.log(`Active run: ${error.conflictingRunId}`);
+      }
+      return {
+        success: false,
+        reason: "duplicate-processing",
+        token: error.token,
+        runId: error.conflictingRunId
+      };
     }
     throw error; // Re-throw other errors
   }
 }
 ```
 
-This pattern is useful when you want to detect and handle duplicate processing attempts instead of letting the workflow fail.
+This pattern is useful when you want to detect duplicate processing inside the workflow. Runtime APIs such as `resumeHook()` and `getRun()` must be called outside workflow functions, for example from an API route or in a step.
+
+### Delegate to the active Run
+
+In idempotency flows, a conflict means another active run already owns the hook token. You can return the duplicate-processing payload from the workflow, resume the active hook to deliver the payload to the existing run, then use `getRun(result.runId)` to wait for, stream, or cancel the active run:
+
+```typescript lineNumbers
+import { getRun, resumeHook, start } from "workflow/api";
+import { processPayment } from "@/workflows/process-payment";
+
+type ProcessPaymentResult =
+  | { success: true; payment: unknown }
+  | {
+      success: false;
+      reason: "duplicate-processing";
+      token: string;
+      runId?: string;
+    };
+
+export async function POST(request: Request) {
+  const { orderId, payment } = await request.json();
+  const run = await start(processPayment, [orderId]);
+  const result = (await run.returnValue) as ProcessPaymentResult;
+
+  if (
+    result.success === false &&
+    result.reason === "duplicate-processing" &&
+    result.runId
+  ) {
+    await resumeHook(result.token, payment); // [!code highlight]
+    const activeRun = getRun(result.runId); // [!code highlight]
+
+    return Response.json({
+      delegatedToRunId: activeRun.runId,
+      result: await activeRun.returnValue
+    });
+  }
+
+  return Response.json(result);
+}
+```
+
+If the caller needs live output instead of the final result, return `activeRun.getReadable()` from the same branch. If the duplicate request should replace the active work, call `await activeRun.cancel()` after inspecting the run.
 
-## When Hook Tokens Are Released
+## When hook tokens are released
 
 Hook tokens are automatically released when:
 
 - The workflow run **completes** (successfully or with an error)
-- The workflow run is **cancelled**
+- The workflow run is **canceled**
 - The hook is explicitly **disposed**
 
 After a workflow completes, its hook tokens become available for reuse by other workflows.
 
-## Best Practices
+## Best practices
 
 1. **Use auto-generated tokens** when possible - they are guaranteed to be unique
 2. **Include unique identifiers** if you need custom tokens (order ID, user ID, etc.)
@@ -122,4 +176,6 @@ After a workflow completes, its hook tokens become available for reuse by other
 ## Related
 
 - [Hooks](/docs/foundations/hooks) - Learn more about using hooks in workflows
+- [getRun](/docs/api-reference/workflow-api/get-run) - Retrieve or control the active run
+- [resumeHook](/docs/api-reference/workflow-api/resume-hook) - Deliver data to the active hook
 - [createWebhook](/docs/api-reference/workflow/create-webhook) - Alternative for fixed webhook URLs

package/docs/errors/index.mdx

@@ -9,43 +9,9 @@ related:
 
 Fix common mistakes when creating and executing workflows in the **Workflow SDK**.
 
-<Cards>
-    <Card href="/docs/errors/fetch-in-workflow" title="fetch-in-workflow">
-        Learn how to use fetch in workflow functions.
-    </Card>
-    <Card href="/docs/errors/hook-conflict" title="hook-conflict">
-        Learn how to handle hook token conflicts between workflows.
-    </Card>
-    <Card href="/docs/errors/node-js-module-in-workflow" title="node-js-module-in-workflow">
-        Learn how to use Node.js modules in workflows.
-    </Card>
-    <Card href="/docs/errors/serialization-failed" title="serialization-failed">
-        Learn how to handle serialization failures in workflows.
-    </Card>
-    <Card href="/docs/errors/start-invalid-workflow-function" title="start-invalid-workflow-function">
-        Learn how to start an invalid workflow function.
-    </Card>
-    <Card href="/docs/errors/timeout-in-workflow" title="timeout-in-workflow">
-        Learn how to handle timing delays in workflow functions.
-    </Card>
-    <Card href="/docs/errors/webhook-invalid-respond-with-value" title="webhook-invalid-respond-with-value">
-        Learn how to use the correct `respondWith` values for webhooks.
-    </Card>
-    <Card href="/docs/errors/webhook-response-not-sent" title="webhook-response-not-sent">
-        Learn how to send responses when using manual webhook response mode.
-    </Card>
-    <Card href="/docs/errors/corrupted-event-log" title="corrupted-event-log">
-        Learn how to handle corrupted or invalid event logs.
-    </Card>
-    <Card href="/docs/errors/step-not-registered" title="step-not-registered">
-        Resolve step not registered errors caused by deployment mismatches.
-    </Card>
-    <Card href="/docs/errors/workflow-not-registered" title="workflow-not-registered">
-        Resolve workflow not registered errors caused by deployment mismatches.
-    </Card>
-</Cards>
+<AutoCards />
 
-## Learn More
+## Learn more
 
 * [API Reference](/docs/api-reference) - Complete API documentation
 * [Foundations](/docs/foundations) - Architecture and core concepts

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

@@ -9,21 +9,25 @@ related:
   - /docs/how-it-works/understanding-directives
 ---
 
+<CopyPrompt
+  text="Fix Node.js module usage inside workflow functions. Search workflow files for imports or direct usage of Node-only APIs such as `fs`, `path`, `crypto`, `process`, `http`, or SDK clients. Remove those imports from files/functions that execute under `&quot;use workflow&quot;`. Create helper functions with `&quot;use step&quot;` for filesystem, crypto, environment, network, database, or SDK work, and call those helpers from the workflow. Keep the workflow function limited to deterministic orchestration, serializable values, `sleep`, hooks, and step calls. Verify the workflow starts without node-js-module-in-workflow errors."
+/>
+
 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.
 
@@ -64,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

@@ -0,0 +1,27 @@
+---
+title: replay-divergence
+description: A workflow replay temporarily followed a path that did not match its recorded events.
+type: troubleshooting
+summary: Understand automatic recovery when a workflow replay diverges from its event history.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/errors/corrupted-event-log
+  - /docs/foundations/errors-and-retries
+---
+
+A replay divergence occurs when one invocation of a workflow cannot consume the durable event history using the promises, hooks, sleeps, or steps it created during replay.
+
+This is an SDK/runtime signal, not an error thrown by your workflow code. It is not catchable inside a workflow function.
+
+## 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.
+
+The runtime automatically queues another replay when an invocation reports `REPLAY_DIVERGENCE`. No terminal `run_failed` event is written during these recovery attempts.
+
+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
+
+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/run-expired.mdx

@@ -0,0 +1,85 @@
+---
+title: run-expired
+description: A run's data passed its retention boundary, so its result can no longer be read.
+type: troubleshooting
+summary: Read a run's result before it expires, or return it through a channel you control.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability/retention
+  - /docs/api-reference/workflow-api/start
+  - /docs/foundations/hooks
+---
+
+## Error
+
+```text
+Run "wrun_..." completed, but its data expired at 2026-08-28T05:02:35.009Z
+and is no longer readable.
+```
+
+Thrown as a `RunExpiredError` from `await run.returnValue`.
+
+## Why this happens
+
+A run's payloads — its input, output and error, and those of its steps — are
+kept only for as long as the World's retention policy says. Its *metadata* —
+id, status, timestamps — usually outlives them. So a run can be readable as a
+record while its result is already gone.
+
+Rather than hand back a placeholder that is indistinguishable from a value the
+workflow genuinely returned, `returnValue` throws.
+
+Two ways to reach it:
+
+- **The run was started with `experimental_retention: 0`.** Its data is
+  deleted the moment it reaches a terminal state, and that deletion races your
+  own read of the result — and generally wins. On these runs, expect this
+  error rather than treating it as an edge case. See
+  [Data retention](/docs/observability/retention).
+- **The run simply aged out.** It finished long enough ago that the World's
+  default retention window has passed.
+
+## How to respond
+
+`RunExpiredError` is terminal. Retrying will not bring the data back, so catch
+Catch the error and use the run's metadata to decide what you want to do.
+
+```typescript lineNumbers
+import { getRun } from "workflow/api"
+import { RunExpiredError } from "workflow/errors"
+
+export async function readResult(runId: string) {
+  try {
+    return await getRun(runId).returnValue
+  } catch (error) {
+    if (RunExpiredError.is(error)) { // [!code highlight]
+      // `runStatus` is the run's terminal status when the World still has
+      // it, so you can tell a successful run whose result is gone from a
+      // failed one whose error is gone.
+      if (error.runStatus === "completed") {
+        // The run succeeded; its result is simply no longer stored.
+      }
+      return null
+    }
+    throw error
+  }
+}
+```
+
+The error carries `runId`, `runStatus` and `expiredAt` when the World reports
+them.
+
+### If you need the result of a zero-retention run
+
+Do not read it back off the run. Send it somewhere you control while the run
+is still executing — a step that writes it to your own store. That is the intended pattern
+for `experimental_retention: 0`: the point of the option is that the platform
+does not keep your data, so the platform cannot also be where you fetch it
+from afterwards.
+
+## Related
+
+If the run is gone entirely — metadata included — the World reports it as
+missing and you get a `WorkflowRunNotFoundError` instead. That means the
+record itself has been cleaned up, not just its payloads.

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.