Standardize the error type in the world spec

Author: pranaygp

.changeset/cruel-houses-sneeze.md

@@ -0,0 +1,5 @@
+---
+"@workflow/world-local": patch
+---
+
+Support for structured errors

.changeset/fix-error-stack-rendering.md

@@ -2,4 +2,4 @@
 "@workflow/web-shared": patch
 ---
 
-Fix error and errorStack rendering to display multiline text correctly
+Support structured error rendering

.changeset/good-icons-love.md

@@ -2,4 +2,4 @@
 "@workflow/core": patch
 ---
 
-Propogate error stack for runs using the new world stack proeprty
+Implement the world's structured error interface

.changeset/postgres-error-stack.md

@@ -2,4 +2,4 @@
 "@workflow/world-postgres": patch
 ---
 
-Add errorStack column to workflow runs and steps tables
+Support structured errors for steps and runs

.changeset/sour-tigers-serve.md

@@ -2,4 +2,4 @@
 "@workflow/errors": patch
 ---
 
-Add stack to WorkflowRunFailedError
+Wire through world's structured errors in WorkflowRunFailedError

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

@@ -2,4 +2,4 @@
 "@workflow/world-vercel": patch
 ---
 
-Serialize error and stack as JSON in error field for Vercel backend
+Support structured errors for steps and runs

packages/core/e2e/e2e.test.ts

@@ -561,13 +561,22 @@ describe('e2e', () => {
       const run = await triggerWorkflow('crossFileErrorWorkflow', []);
       const returnValue = await getWorkflowReturnValue(run.runId);
 
-      // The workflow should fail with the error from the helper module
-      expect(returnValue).toHaveProperty('error');
-      expect(returnValue.error).toContain('Error from imported helper module');
+      // The workflow should fail with error response containing both top-level and cause
+      expect(returnValue).toHaveProperty('name');
+      expect(returnValue.name).toBe('WorkflowRunFailedError');
+      expect(returnValue).toHaveProperty('message');
+
+      // Verify the cause property contains the structured error
+      expect(returnValue).toHaveProperty('cause');
+      expect(returnValue.cause).toBeTypeOf('object');
+      expect(returnValue.cause).toHaveProperty('message');
+      expect(returnValue.cause.message).toContain(
+        'Error from imported helper module'
+      );
 
-      // Verify the stack trace is present and shows correct file paths
-      expect(returnValue).toHaveProperty('stack');
-      expect(typeof returnValue.stack).toBe('string');
+      // Verify the stack trace is present in the cause
+      expect(returnValue.cause).toHaveProperty('stack');
+      expect(typeof returnValue.cause.stack).toBe('string');
 
       // Known issue: SvelteKit dev mode has incorrect source map mappings for bundled imports.
       // esbuild with bundle:true inlines helpers.ts but source maps incorrectly map to 99_e2e.ts
@@ -578,24 +587,27 @@ describe('e2e', () => {
 
       if (!isSvelteKitDevMode) {
         // Stack trace should include frames from the helper module (helpers.ts)
-        expect(returnValue.stack).toContain('helpers.ts');
+        expect(returnValue.cause.stack).toContain('helpers.ts');
       }
 
       // These checks should work in all modes
-      expect(returnValue.stack).toContain('throwError');
-      expect(returnValue.stack).toContain('callThrower');
+      expect(returnValue.cause.stack).toContain('throwError');
+      expect(returnValue.cause.stack).toContain('callThrower');
 
       // Stack trace should include frames from the workflow file (99_e2e.ts)
-      expect(returnValue.stack).toContain('99_e2e.ts');
-      expect(returnValue.stack).toContain('crossFileErrorWorkflow');
+      expect(returnValue.cause.stack).toContain('99_e2e.ts');
+      expect(returnValue.cause.stack).toContain('crossFileErrorWorkflow');
 
       // Stack trace should NOT contain 'evalmachine' anywhere
-      expect(returnValue.stack).not.toContain('evalmachine');
+      expect(returnValue.cause.stack).not.toContain('evalmachine');
 
-      // Verify the run failed
+      // Verify the run failed with structured error
       const { json: runData } = await cliInspectJson(`runs ${run.runId}`);
       expect(runData.status).toBe('failed');
-      expect(runData.error).toContain('Error from imported helper module');
+      expect(runData.error).toBeTypeOf('object');
+      expect(runData.error.message).toContain(
+        'Error from imported helper module'
+      );
     }
   );
 });

packages/core/src/runtime.ts

@@ -205,11 +205,7 @@ export class Run<TResult> {
         }
 
         if (run.status === 'failed') {
-          throw new WorkflowRunFailedError(
-            this.runId,
-            run.error ?? 'Unknown error',
-            run.errorStack
-          );
+          throw new WorkflowRunFailedError(this.runId, run.error);
         }
 
         throw new WorkflowRunNotCompletedError(this.runId, run.status);
@@ -541,9 +537,11 @@ export function workflowEntrypoint(workflowCode: string) {
               );
               await world.runs.update(runId, {
                 status: 'failed',
-                error: errorMessage,
-                errorStack: errorStack,
-                // TODO: include error codes when we define them
+                error: {
+                  message: errorMessage,
+                  stack: errorStack,
+                  // TODO: include error codes when we define them
+                },
               });
               span?.setAttributes({
                 ...Attribute.WorkflowRunStatus('failed'),
@@ -756,9 +754,11 @@ export const stepEntrypoint =
               });
               await world.steps.update(workflowRunId, stepId, {
                 status: 'failed',
-                error: err.message || String(err),
-                errorStack,
-                // TODO: include error codes when we define them
+                error: {
+                  message: err.message || String(err),
+                  stack: errorStack,
+                  // TODO: include error codes when we define them
+                },
               });
 
               span?.setAttributes({
@@ -792,8 +792,10 @@ export const stepEntrypoint =
                 });
                 await world.steps.update(workflowRunId, stepId, {
                   status: 'failed',
-                  error: errorMessage,
-                  errorStack: errorStack,
+                  error: {
+                    message: errorMessage,
+                    stack: errorStack,
+                  },
                 });
 
                 span?.setAttributes({

packages/errors/package.json

@@ -31,7 +31,8 @@
   "devDependencies": {
     "@types/ms": "^2.1.0",
     "@types/node": "catalog:",
-    "@workflow/tsconfig": "workspace:*"
+    "@workflow/tsconfig": "workspace:*",
+    "@workflow/world": "workspace:*"
   },
   "dependencies": {
     "@workflow/utils": "workspace:*",

packages/errors/src/index.ts

@@ -1,4 +1,5 @@
 import { parseDurationToDate } from '@workflow/utils';
+import type { StructuredError } from '@workflow/world';
 import type { StringValue } from 'ms';
 
 const BASE_URL = 'https://useworkflow.dev/err';
@@ -121,8 +122,8 @@ export class WorkflowAPIError extends WorkflowError {
  * Thrown when a workflow run fails during execution.
  *
  * This error indicates that the workflow encountered a fatal error
- * and cannot continue. The `error` property contains details about
- * what caused the failure.
+ * and cannot continue. The `cause` property contains the underlying
+ * error with its message, stack trace, and optional error code.
  *
  * @example
  * ```
@@ -134,18 +135,24 @@ export class WorkflowAPIError extends WorkflowError {
  */
 export class WorkflowRunFailedError extends WorkflowError {
   runId: string;
-  error: string;
-  declare stack: string;
+  declare cause: Error & { code?: string };
+
+  constructor(runId: string, error: StructuredError) {
+    // Create a proper Error instance from the StructuredError to set as cause
+    // NOTE: custom error types do not get serialized/deserialized. Everything is an Error
+    const causeError = new Error(error.message);
+    if (error.stack) {
+      causeError.stack = error.stack;
+    }
+    if (error.code) {
+      (causeError as any).code = error.code;
+    }
 
-  constructor(runId: string, error: string, errorStack?: string) {
-    super(`Workflow run "${runId}" failed: ${error}`, {});
+    super(`Workflow run "${runId}" failed: ${error.message}`, {
+      cause: causeError,
+    });
     this.name = 'WorkflowRunFailedError';
     this.runId = runId;
-    this.error = error;
-    // Override the stack with the workflow's error stack if available
-    if (errorStack !== undefined) {
-      this.stack = errorStack;
-    }
   }
 
   static is(value: unknown): value is WorkflowRunFailedError {