feat(runtime): Improve error handling and stack trace tracking

Enhance error reporting by separating error messages and stack traces
in workflow runs and steps. This change allows for more detailed error
logging and better debugging capabilities by storing both the error
message and its full stack trace separately.

Key changes:
- Add `errorStack` field to workflow runs and steps
- Separate error message from stack trace during error processing
- Improve error logging with more context and detailed information

Author: pranaygp

.changeset/good-icons-love.md

@@ -0,0 +1,5 @@
+---
+"@workflow/core": patch
+---
+
+Propogate error stack for runs using the new world stack proeprty

.changeset/sour-tigers-serve.md

@@ -0,0 +1,5 @@
+---
+"@workflow/errors": patch
+---
+
+Add stack to WorkflowRunFailedError

.changeset/witty-vans-report.md

@@ -0,0 +1,5 @@
+---
+"@workflow/world": patch
+---
+
+Add error stack propogation to steps and runs

.changeset/world-vercel-error-serialization.md

@@ -0,0 +1,5 @@
+---
+"@workflow/world-vercel": patch
+---
+
+Serialize error and stack as JSON in error field for Vercel backend

CLAUDE.md

@@ -160,4 +160,5 @@ This project uses pnpm with workspace configuration. The required version is spe
   - All changed packages should be included in the changeset. Never include unchanged packages.
   - All changes should be marked as "patch". Never use "major" or "minor" modes.
 - Remember to always build any packages that get changed before running downstream tests like e2e tests in the workbench
-- Remember that changes made to one workbench should propogate to all other workbenches. The workflows should typically only be written once inside the example workbench and symlinked into all the other workbenches
+- Remember that changes made to one workbench should propogate to all other workbenches. The workflows should typically only be written once inside the example workbench and symlinked into all the other workbenches
+- When writing changeset, use the `pnpm changeset` command from the root of the repo. Keep the changesets terse (see existing changesets for examples). Try to amke chagnesets that are specific to each modified package so they are targeted. Ensure that any breaking changes are marked as "**BREAKING CHANGE**

packages/core/src/runtime.ts

@@ -206,7 +206,8 @@ export class Run<TResult> {
         if (run.status === 'failed') {
           throw new WorkflowRunFailedError(
             this.runId,
-            run.error ?? 'Unknown error'
+            run.error ?? 'Unknown error',
+            run.errorStack
           );
         }
 
@@ -519,6 +520,8 @@ export function workflowEntrypoint(workflowCode: string) {
               }
             } else {
               const errorName = getErrorName(err);
+              const errorMessage =
+                err instanceof Error ? err.message : String(err);
               let errorStack = getErrorStack(err);
 
               // Remap error stack using source maps to show original source locations
@@ -536,12 +539,10 @@ export function workflowEntrypoint(workflowCode: string) {
                 `${errorName} while running "${runId}" workflow:\n\n${errorStack}`
               );
 
-              // Store both the error message and remapped stack trace
-              const errorString = errorStack || String(err);
-
               await world.runs.update(runId, {
                 status: 'failed',
-                error: errorString,
+                error: errorMessage,
+                errorStack: errorStack,
                 // TODO: include error codes when we define them
               });
               span?.setAttributes({
@@ -738,7 +739,8 @@ export const stepEntrypoint =
             }
 
             if (FatalError.is(err)) {
-              const stackLines = getErrorStack(err).split('\n').slice(0, 4);
+              const errorStack = getErrorStack(err);
+              const stackLines = errorStack.split('\n').slice(0, 4);
               console.error(
                 `[Workflows] "${workflowRunId}" - Encountered \`FatalError\` while executing step "${stepName}":\n  > ${stackLines.join('\n    > ')}\n\nBubbling up error to parent workflow`
               );
@@ -754,9 +756,9 @@ export const stepEntrypoint =
               });
               await world.steps.update(workflowRunId, stepId, {
                 status: 'failed',
-                error: String(err),
+                error: err.message || String(err),
+                errorStack: errorStack,
                 // TODO: include error codes when we define them
-                // TODO: serialize/include the error name and stack?
               });
 
               span?.setAttributes({
@@ -773,7 +775,8 @@ export const stepEntrypoint =
 
               if (attempt >= maxRetries) {
                 // Max retries reached
-                const stackLines = getErrorStack(err).split('\n').slice(0, 4);
+                const errorStack = getErrorStack(err);
+                const stackLines = errorStack.split('\n').slice(0, 4);
                 console.error(
                   `[Workflows] "${workflowRunId}" - Encountered \`Error\` while executing step "${stepName}" (attempt ${attempt}):\n  > ${stackLines.join('\n    > ')}\n\n  Max retries reached\n  Bubbling error to parent workflow`
                 );
@@ -783,13 +786,14 @@ export const stepEntrypoint =
                   correlationId: stepId,
                   eventData: {
                     error: errorMessage,
-                    stack: getErrorStack(err),
+                    stack: errorStack,
                     fatal: true,
                   },
                 });
                 await world.steps.update(workflowRunId, stepId, {
                   status: 'failed',
                   error: errorMessage,
+                  errorStack: errorStack,
                 });
 
                 span?.setAttributes({

packages/errors/src/index.ts

@@ -135,12 +135,17 @@ export class WorkflowAPIError extends WorkflowError {
 export class WorkflowRunFailedError extends WorkflowError {
   runId: string;
   error: string;
+  declare stack: string;
 
-  constructor(runId: string, error: string) {
+  constructor(runId: string, error: string, errorStack?: string) {
     super(`Workflow run "${runId}" failed: ${error}`, {});
     this.name = 'WorkflowRunFailedError';
     this.runId = runId;
     this.error = error;
+    // Override the stack with the workflow's error stack if available
+    if (errorStack) {
+      this.stack = errorStack;
+    }
   }
 
   static is(value: unknown): value is WorkflowRunFailedError {

packages/world-vercel/src/runs.ts

@@ -20,6 +20,66 @@ import {
   makeRequest,
 } from './utils.js';
 
+// Schema for structured error with message and stack
+const StructuredErrorSchema = z.object({
+  message: z.string().optional(),
+  stack: z.string().optional(),
+});
+
+/**
+ * Helper to serialize error + errorStack into a JSON string in the error field.
+ * The error field can be either:
+ * - A plain string (legacy format, just the error message)
+ * - A JSON string with { message, stack } (new format)
+ */
+function serializeError(data: UpdateWorkflowRunRequest): any {
+  const { error, errorStack, ...rest } = data;
+
+  // If we have error or errorStack, serialize as JSON string
+  if (error !== undefined || errorStack !== undefined) {
+    return {
+      ...rest,
+      error: JSON.stringify({ message: error, stack: errorStack }),
+      // Remove errorStack from the request payload
+      errorStack: undefined,
+    };
+  }
+
+  return data;
+}
+
+/**
+ * Helper to deserialize error field from the backend into error + errorStack.
+ * Handles backwards compatibility:
+ * - If error is a JSON string with {message, stack} → parse and split
+ * - If error is a plain string → treat as error message with no stack
+ * - If no error → both undefined
+ */
+function deserializeError(run: any): WorkflowRun {
+  const { error, ...rest } = run;
+
+  if (!error) {
+    return run;
+  }
+
+  // Try to parse as structured error JSON
+  try {
+    const parsed = StructuredErrorSchema.parse(JSON.parse(error));
+    return {
+      ...rest,
+      error: parsed.message,
+      errorStack: parsed.stack,
+    };
+  } catch {
+    // Backwards compatibility: error is just a plain string
+    return {
+      ...rest,
+      error: error,
+      errorStack: undefined,
+    };
+  }
+}
+
 // Local schema for lazy mode with refs instead of data
 const WorkflowRunWithRefsSchema = WorkflowRunSchema.omit({
   input: true,
@@ -36,13 +96,14 @@ const WorkflowRunWithRefsSchema = WorkflowRunSchema.omit({
 function filterRunData(run: any, resolveData: 'none' | 'all'): WorkflowRun {
   if (resolveData === 'none') {
     const { inputRef: _inputRef, outputRef: _outputRef, ...rest } = run;
+    const deserialized = deserializeError(rest);
     return {
-      ...rest,
+      ...deserialized,
       input: [],
       output: undefined,
     };
   }
-  return run;
+  return deserializeError(run);
 }
 
 // Functions
@@ -149,15 +210,17 @@ export async function updateWorkflowRun(
   config?: APIConfig
 ): Promise<WorkflowRun> {
   try {
-    return makeRequest({
+    const serialized = serializeError(data);
+    const run = await makeRequest({
       endpoint: `/v1/runs/${id}`,
       options: {
         method: 'PUT',
-        body: JSON.stringify(data, dateToStringReplacer),
+        body: JSON.stringify(serialized, dateToStringReplacer),
       },
       config,
       schema: WorkflowRunSchema,
     });
+    return deserializeError(run);
   } catch (error) {
     if (error instanceof WorkflowAPIError && error.status === 404) {
       throw new WorkflowRunNotFoundError(id);

packages/world-vercel/src/steps.ts

@@ -16,6 +16,58 @@ import {
   makeRequest,
 } from './utils.js';
 
+// Schema for structured error with message and stack
+const StructuredErrorSchema = z.object({
+  message: z.string().optional(),
+  stack: z.string().optional(),
+});
+
+/**
+ * Helper to serialize error + errorStack into a JSON string in the error field.
+ */
+function serializeStepError(data: UpdateStepRequest): any {
+  const { error, errorStack, ...rest } = data;
+
+  if (error !== undefined || errorStack !== undefined) {
+    return {
+      ...rest,
+      error: JSON.stringify({ message: error, stack: errorStack }),
+      errorStack: undefined,
+    };
+  }
+
+  return data;
+}
+
+/**
+ * Helper to deserialize error field into error + errorStack.
+ * Handles backwards compatibility with plain string errors.
+ */
+function deserializeStepError(step: any): Step {
+  const { error, ...rest } = step;
+
+  if (!error) {
+    return step;
+  }
+
+  // Try to parse as structured error JSON
+  try {
+    const parsed = StructuredErrorSchema.parse(JSON.parse(error));
+    return {
+      ...rest,
+      error: parsed.message,
+      errorStack: parsed.stack,
+    };
+  } catch {
+    // Backwards compatibility: error is just a plain string
+    return {
+      ...rest,
+      error: error,
+      errorStack: undefined,
+    };
+  }
+}
+
 // Local schema for lazy mode with refs instead of data
 const StepWithRefsSchema = StepSchema.omit({
   input: true,
@@ -32,13 +84,14 @@ const StepWithRefsSchema = StepSchema.omit({
 function filterStepData(step: any, resolveData: 'none' | 'all'): Step {
   if (resolveData === 'none') {
     const { inputRef: _inputRef, outputRef: _outputRef, ...rest } = step;
+    const deserialized = deserializeStepError(rest);
     return {
-      ...rest,
+      ...deserialized,
       input: [],
       output: undefined,
     };
   }
-  return step;
+  return deserializeStepError(step);
 }
 
 // Functions
@@ -103,15 +156,17 @@ export async function updateStep(
   data: UpdateStepRequest,
   config?: APIConfig
 ): Promise<Step> {
-  return makeRequest({
+  const serialized = serializeStepError(data);
+  const step = await makeRequest({
     endpoint: `/v1/runs/${runId}/steps/${stepId}`,
     options: {
       method: 'PUT',
-      body: JSON.stringify(data, dateToStringReplacer),
+      body: JSON.stringify(serialized, dateToStringReplacer),
     },
     config,
     schema: StepSchema,
   });
+  return deserializeStepError(step);
 }
 
 export async function getStep(

packages/world/src/runs.ts

@@ -21,6 +21,7 @@ export const WorkflowRunSchema = z.object({
   input: z.array(z.any()),
   output: z.any().optional(),
   error: z.string().optional(),
+  errorStack: z.string().optional(),
   errorCode: z.string().optional(),
   startedAt: z.coerce.date().optional(),
   completedAt: z.coerce.date().optional(),
@@ -44,6 +45,7 @@ export interface UpdateWorkflowRunRequest {
   status?: WorkflowRunStatus;
   output?: SerializedData;
   error?: string;
+  errorStack?: string;
   errorCode?: string;
   executionContext?: Record<string, any>;
 }