fix(core): make step-argument serialization failures catchable in workflow code

.changeset/catchable-step-arg-serialization-errors.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': patch
+---
+
+Step-argument serialization failures now fail the step with a catchable `SerializationError` (via a `step_failed` event, like a step-body failure) instead of failing the run from outside the workflow, and when uncaught they fail the run immediately as a `USER_ERROR` rather than retrying until max queue deliveries.

docs/content/docs/v5/errors/serialization-failed.mdx

@@ -29,6 +29,34 @@ This error can appear when:
 - Serializing step arguments
 - Serializing step return values
 
+## 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:

docs/content/docs/v5/foundations/errors-and-retries.mdx

@@ -139,6 +139,31 @@ callApi.maxRetries = 5; // Retry up to 5 times on failure (6 total attempts)
   step can run up to 4 times total (1 initial attempt + 3 retries).
 </Callout>
 
+## Serialization Failures
+
+A step whose arguments or return value cannot be [serialized](/docs/foundations/serialization) fails like a step whose body threw a `FatalError`: the failure is deterministic, so it skips the retry loop, and a `try/catch` around the step call observes the `SerializationError`:
+
+```typescript lineNumbers
+async function someStep(input: unknown) {
+  "use step";
+  return input;
+}
+
+export async function myWorkflow(input: unknown) {
+  "use workflow";
+
+  try {
+    await someStep(input);
+  } catch (err) {
+    if ((err as Error).name === "SerializationError") {
+      // e.g. `Failed to serialize step arguments at path "..."`
+    }
+  }
+}
+```
+
+Uncaught, the run fails immediately with the `USER_ERROR` code — without retrying. See [serialization-failed](/docs/errors/serialization-failed) for common causes and fixes.
+
 ## Error Codes
 
 When a workflow run fails, the error includes an `errorCode` that classifies the failure, alongside the original thrown value (preserved as `cause`):

packages/core/e2e/e2e.test.ts

@@ -1719,6 +1719,120 @@ describe('e2e', () => {
       );
     });
 
+    describe('serialization failures', () => {
+      test(
+        'step-argument serialization failure is catchable in workflow code',
+        { timeout: 60_000 },
+        async () => {
+          // Passing an unserializable value (a class instance with no serde
+          // model) to a step must fail THAT STEP — step_created +
+          // step_failed — not the whole run, so a try/catch around the step
+          // call observes the SerializationError.
+          const run = await start(
+            await e2e('serializationErrorStepArgsCaught'),
+            []
+          );
+          const result = await run.returnValue;
+
+          expect(result.caught).toBe(true);
+          expect(result.name).toBe('SerializationError');
+          expect(result.messageIncludesStepArguments).toBe(true);
+
+          // The workflow completed (the error was caught) …
+          const { json: runData } = await cliInspectJson(`runs ${run.runId}`);
+          expect(runData.status).toBe('completed');
+
+          // … and the step itself is recorded as failed.
+          const steps = await cliInspectJsonUntil(
+            `steps --runId ${run.runId}`,
+            (json) =>
+              json.some(
+                (s: any) =>
+                  s.stepName.includes('acceptAnyValue') && s.status === 'failed'
+              )
+          );
+          const step = steps.find((s: any) =>
+            s.stepName.includes('acceptAnyValue')
+          );
+          expect(step.status).toBe('failed');
+        }
+      );
+
+      test(
+        'uncaught step-argument serialization failure fails the run as USER_ERROR without redelivery retries',
+        { timeout: 60_000 },
+        async () => {
+          // Regression coverage for the production failure mode where a
+          // step-argument serialization error caused the run to redeliver
+          // until "exceeded max deliveries (49/48)". The run must fail
+          // promptly (well within this test's timeout — 48 redeliveries
+          // with backoff would take many minutes) and classify as
+          // USER_ERROR, not MAX_DELIVERIES_EXCEEDED.
+          const run = await start(
+            await e2e('serializationErrorStepArgsUncaught'),
+            []
+          );
+          const error = await run.returnValue.catch((e: unknown) => e);
+
+          expect(WorkflowRunFailedError.is(error)).toBe(true);
+          assert(WorkflowRunFailedError.is(error));
+          expect(error.errorCode).toBe('USER_ERROR');
+          expect(String(error.message)).toContain(
+            'Failed to serialize step arguments'
+          );
+
+          const { json: runData } = await cliInspectJson(`runs ${run.runId}`);
+          expect(runData.status).toBe('failed');
+          expect(runData.errorCode).toBe('USER_ERROR');
+        }
+      );
+
+      test(
+        'step-return-value serialization failure is catchable in workflow code',
+        { timeout: 60_000 },
+        async () => {
+          // The step executor treats a return-value SerializationError as
+          // fatal (skipping the retry loop) and writes step_failed, so the
+          // workflow's try/catch observes it.
+          const run = await start(
+            await e2e('serializationErrorStepReturnCaught'),
+            []
+          );
+          const result = await run.returnValue;
+
+          expect(result.caught).toBe(true);
+          expect(result.name).toBe('SerializationError');
+          expect(result.messageIncludesReturnValue).toBe(true);
+
+          const { json: runData } = await cliInspectJson(`runs ${run.runId}`);
+          expect(runData.status).toBe('completed');
+        }
+      );
+
+      test(
+        'uncaught step-return-value serialization failure fails the run as USER_ERROR',
+        { timeout: 60_000 },
+        async () => {
+          const run = await start(
+            await e2e('serializationErrorStepReturnUncaught'),
+            []
+          );
+          const error = await run.returnValue.catch((e: unknown) => e);
+
+          expect(WorkflowRunFailedError.is(error)).toBe(true);
+          assert(WorkflowRunFailedError.is(error));
+          expect(error.errorCode).toBe('USER_ERROR');
+          expect(String(error.message)).toContain(
+            'Failed to serialize step return value'
+          );
+
+          const { json: runData } = await cliInspectJson(`runs ${run.runId}`);
+          expect(runData.status).toBe('failed');
+          expect(runData.errorCode).toBe('USER_ERROR');
+        }
+      );
+    });
+
     describe('not registered', () => {
       // JS-only: the workflowId is hand-built in the JS scheme, so on another
       // language it names nothing rather than naming something missing.

packages/core/src/runtime.ts

@@ -3329,6 +3329,54 @@ export function workflowEntrypoint(
                           continue;
                         }
 
+                        // Steps whose arguments failed to serialize were
+                        // finalized by the suspension handler as step_created
+                        // + step_failed (see finalizeUnserializableStep). No
+                        // step-execution message is dispatched for them, so
+                        // when such a step is the only pending work nothing
+                        // would ever re-invoke the run — replay in-process
+                        // over the reloaded log instead. The replay rejects
+                        // the step's promise with the SerializationError,
+                        // which a try/catch around the step call observes;
+                        // uncaught, it propagates out of the workflow body
+                        // and fails the run as a USER_ERROR. Healthy sibling
+                        // steps are not dispatched this pass: the replay
+                        // re-suspends over their already-committed
+                        // step_created events and the next pass dispatches
+                        // them as usual.
+                        if (
+                          suspensionResult.failedStepCorrelationIds.size > 0
+                        ) {
+                          // Join the batched fan-out's trailing chunk commits
+                          // and step-message publishes before continuing,
+                          // exactly like the two joins on the dispatch paths
+                          // below: this invocation must not proceed (and
+                          // eventually ack) before every create and publish
+                          // it launched is durable. A rejection propagates
+                          // like theirs — transient world errors rethrow to
+                          // the queue for redelivery.
+                          await suspensionResult.deferredBatchWork;
+                          // Inline steps whose pair-folded step_started this
+                          // pass already committed (`inlineClaims`) are
+                          // deliberately NOT executed on this pass: the
+                          // forced replay below re-suspends over the same
+                          // pending steps, and owned recovery (the claims
+                          // carry this message's ownerMessageId) re-executes
+                          // them there. Its "previous delivery crashed
+                          // mid-body" log is a misnomer on this path —
+                          // nothing crashed, the bodies were never started.
+                          //
+                          // The failed dehydration may have executed
+                          // workflow-owned code (getters/proxies) before
+                          // throwing; demote to a cold replay rather than
+                          // resume a VM that may have diverged. This is a
+                          // rare terminal-error path, so the replay cost is
+                          // irrelevant next to the divergence risk.
+                          retainedSession = null;
+                          eventLog = nextEventLogLoad(eventLog);
+                          continue;
+                        }
+
                         const pendingSteps = suspensionResult.pendingSteps;
 
                         // Inline execution is gated on ownership. The