@mastra/mcp-docs-server 1.0.0-beta.8 → 1.0.0

package/.docs/raw/workflows/error-handling.mdx

@@ -1,24 +1,204 @@
 ---
 title: "Error Handling | Workflows"
 description: "Learn how to handle errors in Mastra workflows using step retries, conditional branching, and monitoring."
+packages:
+  - "@mastra/core"
 ---
 
 # Error Handling
 
-Mastra provides a built-in retry mechanism for workflows or steps that fail due to transient errors. This is particularly useful for steps that interact with external services or resources that might experience temporary unavailability.
+Mastra workflows support error handling through result status checks after execution, retry policies for transient failures, and lifecycle callbacks for centralized error logging or alerting.
+
+## Handling workflow results
+
+When you run a workflow, the result object contains the status and any errors that occurred.
+
+### Checking the result status
+
+```typescript title="src/run-workflow.ts"
+import { mastra } from "./mastra";
+
+const workflow = mastra.getWorkflow("myWorkflow");
+const run = await workflow.createRun();
+const result = await run.start({ inputData: { value: "test" } });
+
+switch (result.status) {
+  case 'success':
+    console.log('Workflow completed:', result.result);
+    break;
+  case 'failed':
+    console.error('Workflow failed:', result.error);
+    break;
+  case 'suspended':
+    console.log('Workflow suspended, waiting for resume');
+    break;
+}
+```
+
+### Result object structure
+
+The result object contains:
+
+- `status` - The workflow status: `'success'`, `'failed'`, `'suspended'`, or `'tripwire'`
+- `result` - The workflow output (when status is `'success'`)
+- `error` - Error details (when status is `'failed'`)
+- `steps` - Individual step results with their status and output
+
+### Accessing step results
+
+You can inspect individual step results to understand where a failure occurred:
+
+```typescript title="src/run-workflow.ts"
+const result = await run.start({ inputData: { value: "test" } });
+
+if (result.status === 'failed') {
+  // Find which step failed
+  for (const [stepId, stepResult] of Object.entries(result.steps)) {
+    if (stepResult.status === 'failed') {
+      console.error(`Step ${stepId} failed:`, stepResult.error);
+    }
+  }
+}
+```
+
+## Lifecycle callbacks
+
+For scenarios where you need to handle workflow completion without awaiting the result—such as background jobs, fire-and-forget workflows, or centralized logging—you can use lifecycle callbacks.
+
+### onFinish
+
+Called when a workflow completes with any status (success, failed, suspended, or tripwire):
+
+```typescript {8-17} title="src/mastra/workflows/order-workflow.ts"
+import { createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const orderWorkflow = createWorkflow({
+  id: 'order-processing',
+  inputSchema: z.object({ orderId: z.string() }),
+  outputSchema: z.object({ orderId: z.string(), status: z.string() }),
+  options: {
+    onFinish: async (result) => {
+      if (result.status === 'success') {
+        await db.updateOrderStatus(result.result.orderId, result.status);
+      }
+      await analytics.track('workflow_completed', {
+        workflowId: 'order-processing',
+        status: result.status,
+      });
+    },
+  },
+});
+```
+
+The `onFinish` callback receives:
+
+- `status` - The workflow status
+- `result` - The workflow output (on success)
+- `error` - Error details (on failure)
+- `steps` - Individual step results
+- `tripwire` - Tripwire info (if status is `'tripwire'`)
+- `runId` - The unique identifier for this workflow run
+- `workflowId` - The workflow's identifier
+- `resourceId` - Optional resource identifier (if provided when creating the run)
+- `getInitData()` - Function that returns the initial input data
+- `mastra` - The Mastra instance (if workflow is registered with Mastra)
+- `requestContext` - Request-scoped context data
+- `logger` - The workflow's logger instance
+- `state` - The workflow's current state object
+
+### onError
+
+Called only when a workflow fails (status is `'failed'` or `'tripwire'`):
+
+```typescript {8-14} title="src/mastra/workflows/payment-workflow.ts"
+import { createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const paymentWorkflow = createWorkflow({
+  id: 'payment-processing',
+  inputSchema: z.object({ amount: z.number() }),
+  outputSchema: z.object({ transactionId: z.string() }),
+  options: {
+    onError: async (errorInfo) => {
+      await alertService.notify({
+        channel: 'payments-alerts',
+        message: `Payment workflow failed: ${errorInfo.error?.message}`,
+      });
+      await errorTracker.capture(errorInfo.error);
+    },
+  },
+});
+```
+
+The `onError` callback receives:
+
+- `status` - Either `'failed'` or `'tripwire'`
+- `error` - Error details
+- `steps` - Individual step results
+- `tripwire` - Tripwire info (if status is `'tripwire'`)
+- `runId` - The unique identifier for this workflow run
+- `workflowId` - The workflow's identifier
+- `resourceId` - Optional resource identifier (if provided when creating the run)
+- `getInitData()` - Function that returns the initial input data
+- `mastra` - The Mastra instance (if workflow is registered with Mastra)
+- `requestContext` - Request-scoped context data
+- `logger` - The workflow's logger instance
+- `state` - The workflow's current state object
+
+### Using both callbacks
+
+You can use both callbacks together:
+
+```typescript {8-16} title="src/mastra/workflows/pipeline-workflow.ts"
+import { createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const pipelineWorkflow = createWorkflow({
+  id: 'data-pipeline',
+  inputSchema: z.object({ source: z.string() }),
+  outputSchema: z.object({ recordsProcessed: z.number() }),
+  options: {
+    onFinish: async (result) => {
+      // Always log completion
+      await logger.info('Pipeline completed', { status: result.status });
+    },
+    onError: async (errorInfo) => {
+      // Alert on failures
+      await pagerDuty.alert('Data pipeline failed', errorInfo.error);
+    },
+  },
+});
+```
+
+### Error handling in callbacks
+
+Errors thrown inside callbacks are caught and logged—they will not affect the workflow result or cause it to fail. This ensures that callback issues don't break your workflows in production.
+
+```typescript
+options: {
+  onFinish: async (result) => {
+    // If this throws, it's logged but the workflow result is unchanged
+    await externalService.notify(result);
+  },
+}
+```
+
+## Retries
+
+Mastra has a retry mechanism for workflows or steps that fail due to transient errors, for example when steps interact with external services or resources that may be temporarily unavailable.
 
 ## Workflow-level using `retryConfig`
 
 You can configure retries at the workflow level, which applies to all steps in the workflow:
 
-```typescript {8-11} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {7-10} title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
 const step1 = createStep({...});
 
 export const testWorkflow = createWorkflow({
-  // ...
   retryConfig: {
     attempts: 5,
     delay: 2000
@@ -32,14 +212,13 @@ export const testWorkflow = createWorkflow({
 
 You can configure retries for individual steps using the `retries` property. This overrides the workflow-level retry configuration for that specific step:
 
-```typescript {17} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {16} title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
 const step1 = createStep({
-  // ...
   execute: async () => {
-    const response = await // ...
+    const response = await fetch('example-url');
 
     if (!response.ok) {
       throw new Error('Error');
@@ -57,15 +236,14 @@ const step1 = createStep({
 
 You can create alternative workflow paths based on the success or failure of previous steps using conditional logic:
 
-```typescript {15,19,33-34} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {14,18,29-32} title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
 const step1 = createStep({
-  // ...
   execute: async () => {
     try {
-      const response = await // ...
+      const response = await fetch('example-url');
 
       if (!response.ok) {
         throw new Error('error');
@@ -85,9 +263,7 @@ const step1 = createStep({
 const step2 = createStep({...});
 const fallback = createStep({...});
 
-export const testWorkflow = createWorkflow({
-  // ...
-})
+export const testWorkflow = createWorkflow({})
   .then(step1)
   .branch([
     [async ({ inputData: { status } }) => status === "ok", step2],
@@ -100,16 +276,14 @@ export const testWorkflow = createWorkflow({
 
 Use `getStepResult()` to inspect a previous step’s results.
 
-```typescript {10} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {8} title="src/mastra/workflows/test-workflow.ts"
 import { createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
 const step1 = createStep({...});
 
 const step2 = createStep({
-  // ...
   execute: async ({ getStepResult }) => {
-
     const step1Result = getStepResult(step1);
 
     return {
@@ -123,7 +297,7 @@ const step2 = createStep({
 
 Use `bail()` in a step to exit early with a successful result. This returns the provided payload as the step output and ends workflow execution.
 
-```typescript {7} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {7} title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -145,7 +319,7 @@ export const testWorkflow = createWorkflow({...})
 
 Use `throw new Error()` in a step to exit with an error.
 
-```typescript {7} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {7} title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -167,7 +341,7 @@ export const testWorkflow = createWorkflow({...})
 
 You can monitor workflows for errors using `stream`:
 
-```typescript {11} title="src/test-workflow.ts" showLineNumbers copy
+```typescript {11} title="src/test-workflow.ts"
 import { mastra } from "../src/mastra";
 
 const workflow = mastra.getWorkflow("testWorkflow");

package/.docs/raw/workflows/human-in-the-loop.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Human-in-the-loop (HITL) | Workflows"
 description: "Human-in-the-loop workflows in Mastra allow you to pause execution for manual approvals, reviews, or user input before continuing."
+packages:
+  - "@mastra/core"
 ---
 
 # Human-in-the-loop (HITL)
@@ -13,7 +15,7 @@ Human-in-the-loop input works much like [pausing a workflow](/docs/v1/workflows/
 
 ![Pausing a workflow with suspend()](/img/workflows/workflows-suspend.jpg)
 
-```typescript {12-17,22-26} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {12-17,22-26} title="src/mastra/workflows/test-workflow.ts"
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -64,7 +66,7 @@ export const testWorkflow = createWorkflow({
 
 When a workflow is suspended, you can access the payload returned by `suspend()` by identifying the suspended step and reading its `suspendPayload`.
 
-```typescript {12} title="src/test-workflow.ts" showLineNumbers copy
+```typescript {12} title="src/test-workflow.ts"
 const workflow = mastra.getWorkflow("testWorkflow");
 const run = await workflow.createRun();
 
@@ -95,7 +97,7 @@ As with [restarting a workflow](/docs/v1/workflows/suspend-and-resume#restarting
 
 ![Restarting a workflow with resume()](/img/workflows/workflows-resume.jpg)
 
-```typescript {13} showLineNumbers copy
+```typescript {13}
 const workflow = mastra.getWorkflow("testWorkflow");
 const run = await workflow.createRun();
 
@@ -117,9 +119,8 @@ const handleResume = async () => {
 
 Use `bail()` to stop workflow execution at a step without triggering an error. This can be useful when a human explicitly rejects an action. The workflow completes with a `success` status, and any logic after the call to `bail()` is skipped.
 
-```typescript {7-11} showLineNumbers copy
+```typescript {6-10}
 const step1 = createStep({
-  // ...
   execute: async ({ inputData, resumeData, suspend, bail }) => {
     const { userEmail } = inputData;
     const { approved } = resumeData ?? {};
@@ -147,7 +148,7 @@ const step1 = createStep({
 
 For workflows that require input at multiple stages, the suspend pattern remains the same. Each step defines a `resumeSchema`, and `suspendSchema` typically with a reason that can be used to provide user feedback.
 
-```typescript {11-16,21-25} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {11-16,21-25} title="src/mastra/workflows/test-workflow.ts"
 const step1 = createStep({...});
 
 const step2 = createStep({
@@ -196,7 +197,7 @@ export const testWorkflow = createWorkflow({
 
 Each step must be resumed in sequence, with a separate call to `resume()` for each suspended step. This approach helps manage multi-step approvals with consistent UI feedback and clear input handling at each stage.
 
-```typescript {4,11} showLineNumbers copy
+```typescript {4,11}
 const handleResume = async () => {
   const result = await run.resume({
     step: "step-1",

package/.docs/raw/workflows/input-data-mapping.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Input Data Mapping | Workflows"
 description: "Learn how to use workflow input mapping to create more dynamic data flows in your Mastra workflows."
+packages:
+  - "@mastra/core"
 ---
 
 # Input Data Mapping
@@ -18,7 +20,7 @@ In this example the `output` from `step1` is transformed to match the `inputSche
 
 ![Mapping with .map()](/img/workflows/workflows-data-mapping-map.jpg)
 
-```typescript {9} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {9} title="src/mastra/workflows/test-workflow.ts"
 const step1 = createStep({...});
 const step2 = createStep({...});
 
@@ -38,7 +40,7 @@ export const testWorkflow = createWorkflow({...})
 
 Use `inputData` to access the full output of the previous step:
 
-```typescript {3} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3} title="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map(({ inputData }) => {
     console.log(inputData);
@@ -49,7 +51,7 @@ Use `inputData` to access the full output of the previous step:
 
 Use `getStepResult` to access the full output of a specific step by referencing the step's instance:
 
-```typescript {3} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3} title="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map(async ({ getStepResult }) => {
     console.log(getStepResult(step1));
@@ -60,7 +62,7 @@ Use `getStepResult` to access the full output of a specific step by referencing
 
 Use `getInitData` to access the initial input data provided to the workflow:
 
-```typescript {3} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3} title="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map(async ({ getInitData }) => {
       console.log(getInitData());
@@ -71,7 +73,7 @@ Use `getInitData` to access the initial input data provided to the workflow:
 
 To use `mapVariable` import the necessary function from the workflows module:
 
-```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript title="src/mastra/workflows/test-workflow.ts"
 import { mapVariable } from "@mastra/core/workflows";
 ```
 
@@ -79,7 +81,7 @@ import { mapVariable } from "@mastra/core/workflows";
 
 You can rename step outputs using the object syntax in `.map()`. In the example below, the `value` output from `step1` is renamed to `details`:
 
-```typescript {3-6} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3-6} title="src/mastra/workflows/test-workflow.ts"
   .then(step1)
   .map({
     details: mapVariable({
@@ -93,7 +95,7 @@ You can rename step outputs using the object syntax in `.map()`. In the example
 
 You can rename workflow outputs by using **referential composition**. This involves passing the workflow instance as the `initData`.
 
-```typescript {6-9} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {6-9} title="src/mastra/workflows/test-workflow.ts"
 export const testWorkflow = createWorkflow({...});
 
 testWorkflow