### Quick Setup CLI Command

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Use this command to quickly create a new Mastra project via the command line interface.

```bash
npm create mastra@latest
```

--------------------------------

### Alternative Package Managers for Quick Setup

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Commands for creating a new Mastra project using pnpm, yarn, or bun.

```bash
pnpm create mastra@latest
```

```bash
yarn create mastra@latest
```

```bash
bun create mastra@latest
```

--------------------------------

### Fetch Main Documentation Index

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/remote-docs.md

Start by checking the main documentation index at llms.txt to understand the available documentation structure, topics, and sections.

```text
https://mastra.ai/llms.txt
```

--------------------------------

### CLI Flag to Skip Example Agent

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Use this flag with the create command to skip the generation of the example agent.

```bash
npm create mastra@latest --no-example
```

--------------------------------

### Start Postgres Database with Docker

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Use Docker to run a PostgreSQL instance for Mastra AI. Ensure the correct port, database name, and password are set.

```bash
docker run -d \
  --name mastra-postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=mastra \
  -p 5432:5432 \
  postgres:16
```

--------------------------------

### Run Mastra Studio

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/SKILL.md

Start the Mastra Studio development server to access the interactive UI for building and managing Mastra projects. Studio is useful for visual inspection and debugging.

```bash
npm run dev
```

--------------------------------

### Install Mastra and Development Dependencies

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Installs Mastra, TypeScript, and Node types as development dependencies, along with core Mastra and Zod libraries.

```bash
npm install -D typescript @types/node mastra@latest
npm install @mastra/core@latest zod@^4
```

--------------------------------

### Check installed Mastra core version

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/migration-guide.md

Verify the currently installed version of the Mastra core package. This is a crucial first step in the migration process.

```bash
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"ApiName"'
```

--------------------------------

### Quick migration workflow commands

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/migration-guide.md

A sequence of commands to perform a quick migration, including checking the current version, fetching migration guides, updating dependencies, running automated codemods, and checking embedded documentation.

```bash
# 1. Check current version
npm list @mastra/core

# 2. Fetch migration guide from official docs
# Use WebFetch: https://mastra.ai/llms.txt
# Find relevant migration section

# 3. Update dependencies
npm install @mastra/core@latest @mastra/memory@latest @mastra/rag@latest mastra@latest

# 4. Run automated migration (if available)
npx @mastra/codemod@latest v1  # or whatever version

# 5. Check embedded docs for new APIs
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json

# 6. Fix breaking changes using embedded docs lookup
# See embedded-docs.md for how to look up each API

# 7. Test
npm run dev
npm test
```

--------------------------------

### Update all Mastra packages to latest

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/migration-guide.md

Installs the latest versions of all core Mastra packages simultaneously to ensure compatibility during migration.

```bash
npm install @mastra/core@latest @mastra/memory@latest @mastra/rag@latest mastra@latest
```

--------------------------------

### Clone Mastra Skills Repository

Source: https://github.com/mastra-ai/skills/blob/main/README.md

Manually install Mastra skills by cloning the official GitHub repository. After cloning, configure your agent to load skills from this directory.

```bash
git clone https://github.com/mastra-ai/skills.git
```

--------------------------------

### Check Mastra Packages Installation

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/SKILL.md

Verify if Mastra packages are installed in the node_modules directory. This helps determine whether to use embedded or remote documentation.

```bash
ls node_modules/@mastra/
```

--------------------------------

### Enable Verbose Logging with Pino

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Configure Mastra to use Pino logger with 'debug' or 'trace' level for detailed logs. Ensure Pino is installed.

```typescript
const mastra = new Mastra({
  logger: new PinoLogger({
    name: "mastra",
    level: "debug", // or 'trace' for even more detail
  }),
});
```

--------------------------------

### Check Mastra Package Versions

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Verify that all installed @mastra packages are using the same version to prevent compatibility issues. Run these commands in your project's root directory.

```bash
npm list @mastra/core
npm list @mastra/memory
npm list @mastra/rag
```

--------------------------------

### Get details of a specific resource by ID

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

Retrieve detailed information for a specific resource using its ID. The output is projected to show the `data` field using `jq`.

```bash
npx mastra api <resource> get <id> \
  | jq '.data'
```

--------------------------------

### Agent-friendly Markdown URL

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/remote-docs.md

Append .md to any documentation URL to get a clean, agent-friendly markdown version optimized for LLM consumption. This removes navigation and returns pure markdown content.

```text
https://mastra.ai/reference/workflows/workflow-methods/then.md
```

--------------------------------

### Commit Workflow and Execute

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Ensures workflow execution by calling `.commit()` and then starting a new run. This pattern resolves 'Cannot read property 'then' of undefined' errors.

```typescript
const workflow = createWorkflow({
  id: "my-workflow",
  inputSchema: z.object({ data: z.string() }),
  outputSchema: z.object({ result: z.string() }),
})
  .then(step1)
  .then(step2)
  .commit(); // REQUIRED!

// Then execute
const run = await workflow.createRun();
const result = await run.start({ inputData: { data: "test" } });
```

--------------------------------

### Look up new API signatures using embedded docs

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/migration-guide.md

Commands to find information about new API signatures by searching the SOURCE_MAP.json and inspecting type definition files within the installed Mastra core package.

```bash
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"NewApi"'
cat node_modules/@mastra/core/dist/[path]
```

--------------------------------

### Get the latest resource item

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

Retrieve the most recent item of a resource using a `perPage:1` query and projecting the first element of the data array with `jq`. This is part of the fast path for read-only requests.

```bash
npx mastra api <resource> list '{"page":0,"perPage":1}' \
  | jq '.data[0]'
```

--------------------------------

### Create Project Directory and Initialize npm

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Steps to create a new project directory and initialize it with npm.

```bash
mkdir my-first-agent && cd my-first-agent
npm init -y
```

--------------------------------

### Quick Commands Reference

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/embedded-docs.md

A collection of common bash commands for interacting with Mastra package documentation and source code, including listing packages, finding documentation, and viewing type definitions.

```bash
# List installed @mastra packages
ls node_modules/@mastra/
```

```bash
# List available topic documentation
ls node_modules/@mastra/core/dist/docs/references/
```

```bash
# Find specific export in SOURCE_MAP
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"ExportName"'
```

```bash
# Read type definition from path
cat node_modules/@mastra/core/dist/[path-from-source-map]
```

```bash
# View package overview
cat node_modules/@mastra/core/dist/docs/SKILL.md
```

--------------------------------

### Initialize Mastra Storage with PostgresStore

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Initialize the `PostgresStore` with the correct connection string. The `init()` method will create necessary tables if they don't exist.

```typescript
const storage = new PostgresStore({
  connectionString: process.env.DATABASE_URL,
});
await storage.init(); // Creates tables if needed
```

--------------------------------

### Create Mastra Entry Point

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Initializes the Mastra application with the defined agents.

```typescript
import { Mastra } from "@mastra/core";
import { weatherAgent } from "./agents/weather-agent";

export const mastra = new Mastra({
  agents: { weatherAgent },
});
```

--------------------------------

### List All Available Providers

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/model-selection.md

Use this command to list all supported providers in the Mastra model registry.

```bash
node scripts/provider-registry.mjs --list
```

--------------------------------

### Verify Database Connection String

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Ensure your `DATABASE_URL` environment variable correctly points to your PostgreSQL instance, including username, password, host, port, and database name.

```env
DATABASE_URL=postgresql://postgres:password@localhost:5432/mastra
```

--------------------------------

### Environment File Configuration

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Create a .env file to store your API key. Supports keys from various providers like Google, OpenAI, and Anthropic.

```env
GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
```

--------------------------------

### API Discovery Commands

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

Use the narrowest discovery command that can answer the question. Use top-level help only when the resource is unknown.

```bash
npx mastra api trace --help
npx mastra api trace list --help
npx mastra api trace list --schema
npx mastra api --help
```

--------------------------------

### WebFetch for Specific Method Documentation

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/remote-docs.md

After identifying the relevant documentation URL, use the WebFetch tool again to retrieve detailed information about specific methods, including parameters and usage.

```javascript
WebFetch({
  url: "https://mastra.ai/reference/workflows/workflow-methods/then.md",
  prompt: "What are the parameters for the .then() method and how do I use it?"
})
```

--------------------------------

### CLI Flag to Use a Specific Template

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Specify a template name to use for project creation.

```bash
npm create mastra@latest --template <template-name>
```

--------------------------------

### WebFetch for Documentation Lookup

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/remote-docs.md

Use the WebFetch tool to query the main documentation index (llms.txt) for specific information, such as the location of documentation for workflow methods like .then().

```javascript
WebFetch({
  url: "https://mastra.ai/llms.txt",
  prompt: "Where can I find documentation about workflow methods like .then()?"
})
```

--------------------------------

### Add Mastra Skills using .well-known Standard

Source: https://github.com/mastra-ai/skills/blob/main/README.md

Add Mastra skills by pointing the CLI to the Mastra domain, leveraging the .well-known skills discovery standard.

```bash
npx skills add https://mastra.ai/
```

--------------------------------

### Register and Assign Tools to Agent

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Demonstrates the correct pattern for creating, registering tools in a Mastra instance, and assigning them to an agent.

```typescript
// 1. Create tool
const weatherTool = createTool({
  id: "get-weather",
  // ... tool config
});

// 2. Register in Mastra instance
const mastra = new Mastra({
  tools: {
    weatherTool, // or 'weatherTool': weatherTool
  },
});

// 3. Assign to agent
const agent = new Agent({
  id: "weather-agent",
  tools: { weatherTool }, // Reference the tool
  // ... other config
});
```

--------------------------------

### Check Supported Models with Mastra CLI

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Use the Mastra CLI to list supported models. Navigate to the core package's docs directory and consult the `embedded-docs.md` file for lookup instructions.

```bash
# Check supported models
ls node_modules/@mastra/core/dist/docs/
# See embedded-docs.md for lookup instructions
```

--------------------------------

### Project specific fields from a list of resources

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

When the data shape is known, project only the necessary fields (e.g., `id`, `name`, `createdAt`, `status`) from a list of resources using `jq` for a more compact output.

```bash
npx mastra api <resource> list '{"page":0,"perPage":10}' \
  | jq '.data[] | {id, name, createdAt, status}'
```

--------------------------------

### Search for Topic Documentation

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/embedded-docs.md

Use `grep` to search for specific topics within the reference documentation of a Mastra package. This helps locate relevant API information quickly.

```bash
grep -r "Agent" node_modules/@mastra/core/dist/docs/references
```

--------------------------------

### Construct Direct URL Patterns

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/remote-docs.md

Documentation follows predictable URL patterns for overview pages and API references. Use these patterns to construct direct URLs to specific documentation sections.

```text
https://mastra.ai/docs/{topic}/overview
```

```text
https://mastra.ai/reference/{topic}/
```

--------------------------------

### Verify server reachability

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

Before making resource calls, verify server reachability with a cheap check by querying the API schema. This command defaults to `http://localhost:4111` if `$MASTRA_URL` is not set.

```bash
MASTRA_URL="${MASTRA_URL:-http://localhost:4111}"
curl -fsS "$MASTRA_URL/api/system/api-schema" >/dev/null
```

--------------------------------

### List Models for a Specific Provider

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/model-selection.md

Use this command to list all models for a given provider, sorted by newest first. This is useful for verifying model availability and names.

```bash
node scripts/provider-registry.mjs --provider openai
```

```bash
node scripts/provider-registry.mjs --provider anthropic
```

--------------------------------

### List agents with authentication headers

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

For authenticated servers, pass repeatable headers such as `Authorization` using the `--header` flag. Replace `$TOKEN` with the actual authentication token.

```bash
npx mastra api --url "$MASTRA_URL" --header "Authorization: Bearer $TOKEN" agent list
```

--------------------------------

### Specify Correct Model Format

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

When initializing an Agent, use the correct model format, which is `provider/model` (e.g., `openai/gpt-5.4`). Omitting the provider will result in a 'Model not found' error.

```typescript
const agent = new Agent({
  model: "openai/gpt-5.4", // ✅ Correct
  // NOT: model: 'gpt-5.4'       // ❌ Missing provider
});
```

--------------------------------

### List traces with pagination

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

Observability commands like `trace` target `https://observability.mastra.ai` by default. This command lists traces with specified pagination parameters. No `--url` or `--header` is required if environment variables or `.mastra-project.json` are configured.

```bash
npx mastra api trace list '{"page":0,"perPage":10}'
```

--------------------------------

### Project specific fields for a single resource

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

After fetching details for a specific resource by ID, use `jq` to project only the required fields for a focused view.

```bash
npx mastra api <resource> get <id> \
  | jq '.data | {id, name, createdAt, status}'
```

--------------------------------

### Configure Package.json Scripts

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Add 'dev' and 'build' scripts to your package.json for running Mastra development server and build process.

```json
{
  "scripts": {
    "dev": "mastra dev",
    "build": "mastra build"
  }
}
```

--------------------------------

### List agents using default local server

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

Use this command to list agents when connected to a local Mastra dev server. The CLI defaults to `http://localhost:4111`.

```bash
npx mastra api agent list
```

--------------------------------

### Configure Agent Memory with Storage

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Set up agent memory persistence by configuring a storage backend and assigning it to the agent. Ensure consistent threadIds for conversations.

```typescript
// 1. Configure storage
const storage = new PostgresStore({
  connectionString: process.env.DATABASE_URL,
});

// 2. Create memory with storage
const memory = new Memory({
  id: "chat-memory",
  storage,
  options: {
    lastMessages: 10, // How many messages to retrieve
  },
});

// 3. Assign memory to agent
const agent = new Agent({
  id: "chat-agent",
  memory,
});

// 4. Use consistent threadId
await agent.generate("Hello", {
  threadId: "user-123-conversation", // Same threadId for entire conversation
  resourceId: "user-123",
});
```

--------------------------------

### List metric names

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

This command lists available metric names. It targets the default observability endpoint and does not require explicit URL or header configuration if environment variables or project configuration are set.

```bash
npx mastra api metric names
```

--------------------------------

### Find Routes by Path

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

Use curl and jq to find API routes that match a specific path pattern.

```bash
curl -fsS "$MASTRA_URL/api/system/api-schema" \
  | jq '.routes[] | select(.path | contains("/memory"))'
```

--------------------------------

### View Type Definition

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/embedded-docs.md

Read the type definition file for a specific export to understand its constructor parameters, types, and JSDoc comments. This provides the most detailed API information.

```bash
cat node_modules/@mastra/core/dist/agent/agent.d.ts
```

--------------------------------

### List recent resource items

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

Fetch a list of recent items for a resource with a small `perPage` value (e.g., 10) and iterate through the data array using `jq`. This is a common pattern for read-only requests.

```bash
npx mastra api <resource> list '{"page":0,"perPage":10}' \
  | jq '.data[]'
```

--------------------------------

### List agents with a specified server URL

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

When interacting with a Mastra platform or remote server, specify the server URL using the `--url` flag. `$MASTRA_URL` is a placeholder for the actual server URL.

```bash
npx mastra api --url $MASTRA_URL agent list
```

--------------------------------

### Package Overview Documentation Structure

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/embedded-docs.md

This shows the directory structure for embedded documentation within a Mastra package, including the location of package overviews, asset mappings, and individual topic references.

```bash
ls node_modules/@mastra/core/dist/docs/
```

--------------------------------

### Enable ES Modules in package.json

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Add `"type": "module"` to your package.json to enable ES module syntax and resolve import errors.

```json
{
  "type": "module"
}
```

--------------------------------

### Create Weather Tool

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Defines a reusable tool for fetching weather information, including input and output schemas and an execute function.

```typescript
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "get-weather",
  description: "Get current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City name"),
  }),
  outputSchema: z.object({
    output: z.string(),
  }),
  execute: async () => {
    return { output: "The weather is sunny" };
  },
});
```

--------------------------------

### Add Mastra AI Skills via CLI

Source: https://github.com/mastra-ai/skills/blob/main/README.md

Use this command to add the Mastra AI skills to your project using the Mastra CLI.

```bash
npx skills add mastra-ai/skills
```

--------------------------------

### Standard URL for Documentation

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/remote-docs.md

This is the standard URL format for accessing Mastra documentation pages.

```text
https://mastra.ai/reference/workflows/workflow-methods/then
```

--------------------------------

### TypeScript Configuration (tsconfig.json)

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Essential TypeScript configuration for Mastra projects. Ensure 'module' is set to 'ES2022' and 'moduleResolution' to 'bundler' to avoid errors.

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}
```

--------------------------------

### Inspect a Specific Route

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

Use curl and jq to inspect the schema details (path, query, body, response) of a specific API route.

```bash
curl -fsS "$MASTRA_URL/api/system/api-schema" \
  | jq '.routes[] | select(.method == "POST" and .path == "/tools/:toolId/execute") | {pathParamSchema, queryParamSchema, bodySchema, responseShape}'
```

--------------------------------

### Create Weather Agent

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/create-mastra.md

Defines a weather agent with specific instructions, model, and access to the weather tool. Ensure the model format is 'provider/model-name'.

```typescript
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";

export const weatherAgent = new Agent({
  id: "weather-agent",
  name: "Weather Agent",
  instructions: `
      You are a helpful weather assistant that provides accurate weather information.

      Your primary function is to help users get weather details for specific locations. When responding:
      - Always ask for a location if none is provided
      - If the location name isn't in English, please translate it
      - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  model: "google/gemini-2.5-pro",
  tools: { weatherTool },
});
```

--------------------------------

### Directly Assign Tool to Agent

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

An alternative pattern for assigning a tool directly within the agent's configuration.

```typescript
const agent = new Agent({
  id: "weather-agent",
  tools: {
    weatherTool: createTool({ id: "get-weather" /* ... */ }),
  },
});
```

--------------------------------

### Load Environment Variables in Node.js

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Import `dotenv/config` at the top of your entry file to load environment variables from your `.env` file into `process.env`.

```typescript
import "dotenv/config"; // At top of entry file
```

--------------------------------

### Run Mastra codemod for version upgrade

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/migration-guide.md

Executes an automated migration script provided by the Mastra codemod package to assist with upgrading to a specified version.

```bash
npx @mastra/codemod@latest [version]
```

--------------------------------

### Verify API Key Existence

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Check if required environment variables, such as `OPENAI_API_KEY`, are set before proceeding to prevent runtime errors.

```typescript
if (!process.env.OPENAI_API_KEY) {
  throw new Error("OPENAI_API_KEY is required");
}
```

--------------------------------

### Implement Tool Suspension and Resumption

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Tools can suspend execution and resume later using `suspendSchema` and `resumeSchema`. Ensure `workflow.resume()` or `agent.generate()` is called with `resumeData` upon resumption.

```typescript
const approvalTool = createTool({
  id: "approval",
  inputSchema: z.object({ request: z.string() }),
  outputSchema: z.object({ approved: z.boolean() }),
  suspendSchema: z.object({ requestId: z.string() }),
  resumeSchema: z.object({ approved: z.boolean() }),
  execute: async (input, context) => {
    if (!context.resumeData) {
      // First call - suspend
      const requestId = generateId();
      context.suspend({ requestId });
      return; // Execution pauses here
    }

    // Resumed - use resumeData
    return { approved: context.resumeData.approved };
  },
});

// Resume the workflow/agent
await run.resume({
  resumeData: { approved: true },
});
```

--------------------------------

### Provide Storage for Memory Creation

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Ensure storage is always provided when initializing a Memory instance to avoid errors.

```typescript
const memory = new Memory({
  id: "my-memory",
  storage: postgresStore, // REQUIRED
  options: {
    lastMessages: 10,
  },
});
```

--------------------------------

### Configure Vector Store and Embedder for Semantic Recall

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

To enable semantic recall, a vector store and an embedder must be configured, and `semanticRecall` must be set to true in the memory options.

```typescript
const memory = new Memory({
  id: "semantic-memory",
  storage: postgresStore,
  vector: chromaVectorStore, // REQUIRED for semantic recall
  embedder: openaiEmbedder, // REQUIRED for semantic recall
  options: {
    lastMessages: 10,
    semanticRecall: true, // REQUIRED
  },
});
```

--------------------------------

### Check TypeScript compilation

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/migration-guide.md

Ensures that the TypeScript code compiles without errors after migration, using the --noEmit flag to only check for compilation issues.

```bash
npx tsc --noEmit
```

--------------------------------

### Update Tool execute signature

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/migration-guide.md

Illustrates how to update the 'execute' function signature within a tool based on changes identified between old and new API definitions. The new signature includes additional context parameters.

```typescript
// Old (from docs)
execute: async (input) => { ... }

// New (from embedded docs)
execute: async (inputData, context) => { ... }
```

--------------------------------

### Update Workflow State with setState

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Demonstrates how to correctly update and access workflow state across steps using `setState`. This prevents issues with state not updating or `getStepResult()` returning undefined.

```typescript
const step1 = createStep({
  id: "step1",
  execute: async ({ state, setState }) => {
    // Update state
    await setState({ ...state, counter: (state.counter || 0) + 1 });
    return { result: "done" };
  },
});

// Access state in subsequent steps
const step2 = createStep({
  id: "step2",
  execute: async ({ state }) => {
    console.log(state.counter); // Access updated state
    return { result: "complete" };
  },
});
```

--------------------------------

### Define Tool Input Schema with Zod

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Use Zod to define input schemas for tools, ensuring correct validation and type safety. Make fields optional explicitly using `.optional()`.

```typescript
const tool = createTool({
  id: "my-tool",
  inputSchema: z.object({
    name: z.string(),
    age: z.number().optional(), // Make optional fields explicit
  }),
  execute: async (input) => {
    // input is validated and typed
    return { result: `Hello ${input.name}` };
  },
});

// Correct usage
await tool.execute({ name: "Alice" }); // Works
await tool.execute({ name: "Bob", age: 30 }); // Works
await tool.execute({ age: 30 }); // ERROR: name is required
```

--------------------------------

### Validate TypeScript Configuration

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Check your TypeScript compiler configuration to ensure it matches expected settings, such as target and module versions. This command displays the effective tsconfig.json.

```bash
npx tsc --showConfig
# Verify target: ES2022, module: ES2022
```

--------------------------------

### Find Export Path in Source Map

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/embedded-docs.md

Locate the file path for a specific export within a Mastra package by searching the `SOURCE_MAP.json` file. This is useful for finding the exact type definition file.

```bash
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
```

--------------------------------

### Fix 'Cannot find module' with tsconfig.json

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/common-errors.md

Update your tsconfig.json to use ES2022 module settings to resolve import errors.

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler"
  }
}
```

--------------------------------

### Mastra API Output Envelopes

Source: https://github.com/mastra-ai/skills/blob/main/skills/mastra/references/mastra-api.md

These are the standard JSON envelopes returned by the Mastra API for data, paginated data, and errors.

```json
{ "data": {} }
{ "data": [], "page": { "total": 0, "page": 0, "perPage": 0, "hasMore": false } }
{ "error": { "code": "...", "message": "...", "details": {} } }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.