@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.13

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

@@ -5,7 +5,168 @@ description: "Learn how to handle errors in Mastra workflows using step retries,
 
 # 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" showLineNumbers copy
+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" showLineNumbers copy
+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-15} title="src/mastra/workflows/order-workflow.ts" showLineNumbers copy
+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) => {
+      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'`)
+
+### onError
+
+Called only when a workflow fails (status is `'failed'` or `'tripwire'`):
+
+```typescript {8-14} title="src/mastra/workflows/payment-workflow.ts" showLineNumbers copy
+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'`)
+
+### Using both callbacks
+
+You can use both callbacks together:
+
+```typescript {8-16} title="src/mastra/workflows/pipeline-workflow.ts" showLineNumbers copy
+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`
 

package/.docs/raw/workflows/overview.mdx

@@ -315,7 +315,7 @@ When running the local mastra server, all active workflow runs will be restarted
 
 ## Using `RequestContext`
 
-Use [RequestContext](/docs/v1/server-db/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
+Use [RequestContext](/docs/v1/server/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
 
 ```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers
 export type UserTier = {
@@ -336,7 +336,7 @@ const step1 = createStep({
 });
 ```
 
-> See [Request Context](/docs/v1/server-db/request-context) for more information.
+> See [Request Context](/docs/v1/server/request-context) for more information.
 
 ## Testing with Studio
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.0.0-beta.13
+
+### Patch Changes
+
+- Updated dependencies [[`919a22b`](https://github.com/mastra-ai/mastra/commit/919a22b25876f9ed5891efe5facbe682c30ff497)]:
+  - @mastra/core@1.0.0-beta.13
+
+## 1.0.0-beta.12
+
+### Patch Changes
+
+- Updated dependencies [[`d5ed981`](https://github.com/mastra-ai/mastra/commit/d5ed981c8701c1b8a27a5f35a9a2f7d9244e695f), [`9650cce`](https://github.com/mastra-ai/mastra/commit/9650cce52a1d917ff9114653398e2a0f5c3ba808), [`932d63d`](https://github.com/mastra-ai/mastra/commit/932d63dd51be9c8bf1e00e3671fe65606c6fb9cd), [`b760b73`](https://github.com/mastra-ai/mastra/commit/b760b731aca7c8a3f041f61d57a7f125ae9cb215), [`695a621`](https://github.com/mastra-ai/mastra/commit/695a621528bdabeb87f83c2277cf2bb084c7f2b4), [`2b459f4`](https://github.com/mastra-ai/mastra/commit/2b459f466fd91688eeb2a44801dc23f7f8a887ab), [`486352b`](https://github.com/mastra-ai/mastra/commit/486352b66c746602b68a95839f830de14c7fb8c0), [`09e4bae`](https://github.com/mastra-ai/mastra/commit/09e4bae18dd5357d2ae078a4a95a2af32168ab08), [`24b76d8`](https://github.com/mastra-ai/mastra/commit/24b76d8e17656269c8ed09a0c038adb9cc2ae95a), [`243a823`](https://github.com/mastra-ai/mastra/commit/243a8239c5906f5c94e4f78b54676793f7510ae3), [`486352b`](https://github.com/mastra-ai/mastra/commit/486352b66c746602b68a95839f830de14c7fb8c0), [`c61fac3`](https://github.com/mastra-ai/mastra/commit/c61fac3add96f0dcce0208c07415279e2537eb62), [`6f14f70`](https://github.com/mastra-ai/mastra/commit/6f14f706ccaaf81b69544b6c1b75ab66a41e5317), [`09e4bae`](https://github.com/mastra-ai/mastra/commit/09e4bae18dd5357d2ae078a4a95a2af32168ab08), [`4524734`](https://github.com/mastra-ai/mastra/commit/45247343e384717a7c8404296275c56201d6470f), [`2a53598`](https://github.com/mastra-ai/mastra/commit/2a53598c6d8cfeb904a7fc74e57e526d751c8fa6), [`c7cd3c7`](https://github.com/mastra-ai/mastra/commit/c7cd3c7a187d7aaf79e2ca139de328bf609a14b4), [`847c212`](https://github.com/mastra-ai/mastra/commit/847c212caba7df0d6f2fc756b494ac3c75c3720d), [`6f941c4`](https://github.com/mastra-ai/mastra/commit/6f941c438ca5f578619788acc7608fc2e23bd176)]:
+  - @mastra/core@1.0.0-beta.12
+
 ## 1.0.0-beta.11
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.0.0-beta.11",
+  "version": "1.0.0-beta.13",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "@modelcontextprotocol/sdk": "^1.17.5",
     "jsdom": "^26.1.0",
     "zod": "^3.25.76",
-    "@mastra/core": "1.0.0-beta.11",
+    "@mastra/core": "1.0.0-beta.13",
     "@mastra/mcp": "^1.0.0-beta.6"
   },
   "devDependencies": {
@@ -46,7 +46,7 @@
     "typescript": "^5.8.3",
     "vitest": "4.0.12",
     "@internal/lint": "0.0.53",
-    "@mastra/core": "1.0.0-beta.11"
+    "@mastra/core": "1.0.0-beta.13"
   },
   "homepage": "https://mastra.ai",
   "repository": {

package/.docs/organized/changelogs/%40internal%2Fai-sdk-v4.md

@@ -1 +0,0 @@
-No changelog available.

package/.docs/raw/deployment/cloud-providers/index.mdx

@@ -1,55 +0,0 @@
----
-title: "Cloud Providers | Deployment"
-description: "Deploy your Mastra applications to popular cloud providers."
----
-
-# Cloud Providers
-
-Standalone Mastra applications can be deployed to popular cloud providers, see one of the following guides for more information:
-
-- [Amazon EC2](/docs/v1/deployment/cloud-providers/amazon-ec2)
-- [AWS Lambda](/docs/v1/deployment/cloud-providers/aws-lambda)
-- [Azure App Services](/docs/v1/deployment/cloud-providers/azure-app-services)
-- [Cloudflare](/docs/v1/deployment/cloud-providers/cloudflare-deployer)
-- [Digital Ocean](/docs/v1/deployment/cloud-providers/digital-ocean)
-- [Netlify](/docs/v1/deployment/cloud-providers/netlify-deployer)
-- [Vercel](/docs/v1/deployment/cloud-providers/vercel-deployer)
-
-For self-hosted Node.js server deployment, see the [Creating A Mastra Server](/docs/v1/deployment/building-mastra) guide.
-
-## Prerequisites
-
-Before deploying to a cloud provider, ensure you have:
-
-- A [Mastra application](/guides/v1/getting-started/quickstart)
-- Node.js `v22.13.0` or later
-- A GitHub repository for your application (required for most CI/CD setups)
-- Domain name management access (for SSL and HTTPS)
-- Basic familiarity with server setup (e.g. Nginx, environment variables)
-
-## LibSQLStore
-
-`LibSQLStore` writes to the local filesystem, which is not supported in cloud environments that use ephemeral file systems. If you're deploying to platforms like AWS Lambda, Netlify, Azure App Services, or Digital Ocean App Platform, you must remove all usage of `LibSQLStore`.
-
-Specifically, ensure you've removed it from all Mastra files, including configuration on the main Mastra instance and any agents using it, e.g. for memory storage.
-
-```diff title="src/mastra/index.ts"
- export const mastra = new Mastra({
--  storage: new LibSQLStore({
--    id: 'mastra-storage',
--    url: ":memory:",
--  }),
- });
-```
-
-```diff
- export const weatherAgent = new Agent({
-   id: "weather-agent",
-   memory: new Memory({
--    storage: new LibSQLStore({
--      id: 'mastra-storage',
--      url: "file:../mastra.db",
--    }),
-   }),
- });
-```