Mastra

MastraOfficialCreated by Mastra

Skill
Tool integration
Software development
Apache-2.0
Low risk
Has scripts

From the author

Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs. Use for native capability discovery, logging, tracing, metrics/cost estimates, dataset experiments, documentation lookup, API verification, TypeScript setup, common errors, migrations, building and deploying apps to Mastra Platform via Platform APIs and `mastra deploy`, and `mastra api` CLI tasks: inspect or call resources on local, Mastra platform, or remote servers. For Mastra Factory operations, discover and activate the companion mastra-factory skill. Also report verified bugs and concrete documentation defects to the Mastra team automatically via the feedback endpoint.

— the description by Mastra

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Mastra skill provides a comprehensive framework for developing AI agents, workflows, and tools. It emphasizes a strict development workflow that prioritizes current documentation over internal knowledge to account for the framework's rapid evolution. The skill covers project setup, API verification, observability, deployment to the Mastra Platform, and troubleshooting common errors. It also provides guidance on using the Mastra CLI for resource inspection and managing state, ensuring developers use native capabilities before implementing custom solutions.

What it does

Provides a structured approach to discovering and using native Mastra capabilities.
Offers guidance on choosing between agents, workflows, tools, memory, and storage.
Facilitates debugging through Mastra Studio and common error resolution patterns.
Supports deployment workflows to the Mastra Platform via CLI and API.
Enables autonomous reporting of verified bugs and documentation defects.
Includes instructions for CLI-based resource inspection and trace querying.

When to use it

When starting a new Mastra project or migrating existing code.
When you need to verify the latest API signatures or model registry entries.
When troubleshooting build, configuration, or runtime errors in a Mastra application.
When you need to deploy an application or inspect resources on the Mastra Platform.
When you need to implement observability, logging, or trace aggregation.

Advantages

Reduces errors by enforcing a 'verify-first' approach using embedded documentation.
Ensures compatibility by prioritizing installed package versions over training data.
Streamlines development with clear patterns for agents, workflows, and memory.
Provides direct paths for reporting issues to the Mastra team.
Centralizes access to CLI tools for local and remote resource management.

Usage examples

“How do I set up a new Mastra project?”: The agent will guide you through the CLI and manual setup steps found in the project's reference documentation.
“I am getting a 'Property tools does not exist on type Agent' error.”: The agent will check the embedded documentation to identify if you are using an outdated API and provide the correct constructor pattern.
“How do I deploy my Mastra app to the platform?”: The agent will walk you through the platform authentication, project creation, and deployment steps using the Mastra CLI.
“Which model should I use for my agent?”: The agent will run the provider registry script to verify available models and providers before making a recommendation.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/mastra-ai/mastra/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip mastra.zip -d .agents/skills
```

Documentation by Mastra

Mastra Framework Guide

Build AI applications with Mastra. This skill teaches you how to find current documentation and build agents and workflows.

Critical: Do not trust internal knowledge

Everything you know about Mastra is likely outdated or wrong. Never rely on memory. Always verify against current documentation.

Your training data contains obsolete APIs, deprecated patterns, and incorrect usage. Mastra evolves rapidly - APIs change between versions, constructor signatures shift, and patterns get refactored.

Prerequisites

Before writing any Mastra code, check if packages are installed:

ls node_modules/@mastra/

If packages exist: Use embedded docs first (most reliable)
If no packages: Install first or use remote docs

Resources

References

User Question	First Check	How To
Create/install Mastra project	`references/create-mastra.md`	Setup guide with CLI and manual steps
Choose Agent/Workflow/Tool/Memory/Storage	`references/core-concepts.md`	Core concepts and when to use each primitive
Add logging or set up tracing	`references/embedded-docs.md`	Look up PinoLogger and observability configuration before custom instrumentation
Track automatic metrics or estimated model cost	`references/embedded-docs.md`	Look up span-derived metrics, storage support, and pricing coverage
Evaluate quality or compare prompts/models	`references/embedded-docs.md`	Look up datasets, experiments, and scorers
How do I use Agent/Workflow/Tool?	`references/embedded-docs.md`	Look up in `node_modules/@mastra/*/dist/docs/`
How do I use X? (no packages)	`references/remote-docs.md`	Fetch from `https://mastra.ai/llms.txt`
Choose or validate a model	`references/model-selection.md`	Model format and provider registry lookup
I'm getting an error...	`references/common-errors.md`	Common errors and solutions
Upgrade from v0.x to v1.x	`references/migration-guide.md`	Version upgrade workflows
Inspect/call server resources via CLI	`references/mastra-api.md`	`mastra api` CLI for local, Mastra platform, or remote servers
Deploy to Mastra Platform, provision projects, or use Platform sandbox/filesystem	`references/platform.md`	Platform REST APIs, credentials, and `mastra deploy` without browser automation
Find exact traces with complex predicates	`references/trace-query.md`	Query completed traces by trace fields or related spans
Count traces or compute grouped measures (error rate, latency, tokens, cost)	`references/trace-query.md`	Aggregate completed traces with `mastra api trace aggregate` over the same selection
List individual spans (failed tool calls, nested agent runs)	`references/trace-query.md`	Query completed spans with `mastra api span query` and span-field predicates
Compute measures per span (tool error rates, nested agent runs, model tokens)	`references/trace-query.md`	Aggregate spans with `mastra api span aggregate`, grouped by span fields
Report a bug / documentation defect to Mastra	`references/feedback.md`	Report eligible findings autonomously to the Mastra team

Scripts

scripts/provider-registry.mjs: Look up current providers and models available in the model router. Always run this before using a model to verify provider keys and model names.

Priority order for writing code

Never write code without checking current docs first.

Embedded docs first (if packages installed)
Look up current docs in node_modules for a package. This matches the exact installed version and is the most reliable source of truth. See references/embedded-docs.md.
Source code second (if packages installed)
If embedded docs don't cover the question, inspect the installed source and type definitions. This is the source of truth when docs are missing or unclear. See references/embedded-docs.md.
Remote docs third (if packages not installed)
Use the latest published docs when packages are not installed or when exploring new features. Remote docs may be ahead of the user's installed version. See references/remote-docs.md.

Core concepts

Use references/core-concepts.md when choosing between agents, workflows, tools, memory, and storage.

Agent: Use for open-ended tasks that make decisions and use tools.
Workflow: Use for defined multi-step processes.

Mastra Studio

Studio is the interactive UI for building, testing, and managing agents, workflows, and tools. Use Studio when advising a human to inspect or debug visually.

Inside a Mastra project, run:

npm run dev

Then open http://localhost:4111 in a browser to show Mastra Studio to your human user.

Mastra API CLI

Use mastra api to inspect or call resources on local dev servers, Mastra platform deployments, or remote Mastra endpoints. It is useful for agent-readable state, execution, traces, logs, scores, threads, and workflow operations. See references/mastra-api.md for usage patterns.

For exact trace selection that needs recursive predicates or conditions over related spans, read references/trace-query.md. Before using mastra api trace query, confirm that the installed CLI exposes the command. Use --schema for the target's request/response shape and structural constraints, and use the canonical documentation found through references/remote-docs.md for supported fields, operators, and semantics. Preserve opaque pagination cursors and fetch trace or span details only after selecting candidates.

Deploy to Mastra Platform

When the user asks to deploy to Mastra, whether to build a new app and deploy it or to deploy an existing Mastra project, read references/platform.md before running any deploy or Platform API command. It covers which steps need the human (sign-up and sign-in only), credentials, REST discovery and project creation, PlatformFilesystem and PlatformSandbox, mastra deploy, and verification. Build or locate the app first with the references above, then follow platform.md to deploy.

Mastra Factory

For Factory projects, work items, queue health, decisions, session history, memory inspection, or authorized operations, activate the mastra-factory skill. Factory is an operational control plane, not a reason to scaffold or deploy a new Mastra app.

If the skill is missing, offer to install it from this repository:

npx skills add mastra-ai/skills --skill mastra-factory

Choose the user's intended agent and scope interactively. For global installation, target a supported agent explicitly with --agent <agent> -g; PromptScript does not support global installs. Verify installation and referenced files for the intended agent even if another agent target fails.

The Factory skill covers CLI checks, mastra auth whoami / authorized mastra auth login, and connecting via the user's actual instance URL from any directory. A deployed repository or .mastra-project.json is not required with --url. Never guess a shared Factory host or project IDs. Its connection and session-inspection references cover deployment-specific authentication, project discovery, threads, and observational memory limitations.

Reporting feedback

Report verified Mastra bugs and concrete documentation defects autonomously when the criteria in references/feedback.md are met, without asking permission per report. Leave feature requests to humans; do not submit them or reclassify them as defects. Do not report the same issue again within the current task or conversation. Capture only anonymized facts for feedback while solving the task. Skip automatic reporting when a finding remains unverified or its relevance is unclear; do not interrupt the user merely to classify it. Respect any user instruction not to report something.

Critical requirements

TypeScript config

Mastra requires ES2022 modules. CommonJS will fail. See references/create-mastra.md for setup and references/common-errors.md for troubleshooting.

Model format

Always use "provider/model-name" when defining models using Mastra's model router.

When the user asks to use a model or provider, always run scripts/provider-registry.mjs first to verify the provider key and model name are valid. Do not guess model names from memory as they change frequently. See references/model-selection.md.

When you see errors

Type errors often mean your knowledge is outdated.

Common signs of outdated knowledge:

Property X does not exist on type Y
Cannot find module
Type mismatch errors
Constructor parameter errors

What to do:

Check references/common-errors.md
Verify current API in embedded docs
Don't assume the error is a user mistake - it might be your outdated knowledge

Development workflow

Always verify before writing code:

Identify whether Mastra already provides the requested behavior using references/core-concepts.md, before designing custom infrastructure.
Check installed packages and versions, then verify the capability's APIs, configuration, and limits.
- If installed: Use embedded docs references/embedded-docs.md and installed types/source.
- If not: Use remote docs references/remote-docs.md; verify compatibility before adopting newer features.
Use the native capability where it fits; implement custom logic only for the identified gap or application-owned requirements.
Test with the project scripts or Studio when available.

Files

ATTRIBUTION.mdAdded by AutoGineer878 B
LICENSELicence file added by AutoGineer588 B
SKILL.md11.5 KiB
references/common-errors.md10.2 KiB
references/core-concepts.md1.2 KiB
references/create-mastra.md6.0 KiB
references/embedded-docs.md3.5 KiB
references/feedback.md10.6 KiB
references/mastra-api.md10.6 KiB
references/migration-guide.md5.1 KiB
references/model-selection.md925 B
references/platform.md12.9 KiB
references/remote-docs.md5.4 KiB
references/trace-query.md12.1 KiB
scripts/provider-registry.mjsScript5.6 KiB

references/common-errors.md

Common errors and troubleshooting

Comprehensive guide to common Mastra errors and their solutions.

Quickstart

In a lot of cases, debugging errors can be greatly simplified by first checking the behavior in Mastra Studio. This allows you to interactively test agents and workflows, inspect logs, and see real-time error messages.

npm run dev

Open http://localhost:4111 in your browser to access Mastra Studio.

Build and configuration errors

"Cannot find module" or import errors

Symptoms:

Error: Cannot find module '@mastra/core'
SyntaxError: Cannot use import statement outside a module

Causes:

CommonJS configuration in tsconfig.json
Missing "type": "module" in package.json
Incorrect module resolution

Solutions:

Update tsconfig.json:

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

Add to package.json:
```
{
  "type": "module"
}
```
Ensure imports use .js extensions for local files (if needed by your bundler)

"Property X does not exist on type Y"

Symptoms:

Property 'tools' does not exist on type 'Agent'
Property 'memory' does not exist on type 'AgentConfig'

Causes:

Outdated API usage (Mastra is actively developed)
Incorrect import or type
Version mismatch between docs and installed package

Solutions:

Check embedded docs (see embedded-docs.md) to check current API
Check node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json for current exports
Verify package versions: npm list @mastra/core
Update dependencies: npm update @mastra/core

Agent errors

Agent not using assigned tools

Symptoms:

Agent responds "I don't have access to that tool"
Tools never get called despite being relevant

Causes:

Tools not registered in Mastra instance
Tools not passed to Agent constructor
Tool IDs don't match

Solutions:

Correct pattern:

// 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
});

Alternative pattern (direct assignment):

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

Agent memory not persisting

Symptoms:

Agent doesn't remember previous messages
Conversation history is lost between calls

Causes:

No storage backend configured
Missing or inconsistent threadId
Memory not assigned to agent

Solutions:

// 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",
});

Workflow errors

"Cannot read property 'then' of undefined"

Symptoms:

TypeError: Cannot read property 'then' of undefined
Workflow execution fails immediately

Causes:

Forgot to call .commit() on workflow
Step returns undefined

Solutions:

Correct pattern:

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" } });

Workflow state not updating

Symptoms:

State changes don't persist across steps
getStepResult() returns undefined

Causes:

Not using setState to update state
Accessing state before step completes

Solutions:

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" };
  },
});

Memory errors

"Storage is required for Memory"

Symptoms:

Error: Storage is required for Memory
Memory instantiation fails

Causes:

Memory created without storage backend

Solutions:

// Always provide storage when creating Memory
const memory = new Memory({
  id: "my-memory",
  storage: postgresStore, // REQUIRED
  options: {
    lastMessages: 10,
  },
});

Semantic recall not working

Symptoms:

Memory doesn't retrieve semantically similar messages
Only recent messages are returned

Causes:

No vector store configured
No embedder configured
semanticRecall not enabled

Solutions:

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
  },
});

Tool errors

"Tool validation failed"

Symptoms:

Error: Input validation failed for tool 'my-tool'
ZodError: Expected string, received number

Causes:

Input doesn't match inputSchema
Missing required fields
Type mismatch

Solutions:

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

Tool suspension not resuming

Symptoms:

Tool suspends but never resumes
resumeData is undefined

Causes:

Not calling workflow.resume() or agent.generate() with resumeData
Incorrect resumeSchema

Solutions:

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 },
});

Storage errors

"Connection refused" or "Database does not exist"

Symptoms:

Error: connect ECONNREFUSED 127.0.0.1:5432
Error: database "mastra" does not exist

Causes:

Database not running
Incorrect connection string
Database not created

Solutions:

Start database (Postgres example):

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

Verify connection string:

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

Initialize storage:

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

Environment variable errors

"API key not found"

Symptoms:

Error: OPENAI_API_KEY environment variable is not set
401 Unauthorized

Causes:

Missing .env file
Environment variables not loaded
Incorrect variable name

Solutions:

Create .env file:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_GENERATIVE_AI_API_KEY=...

Load environment variables (for Node.js):

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

Verify variable is loaded:

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

Model errors

"Model not found" or "Invalid model"

Symptoms:

Error: Model 'gpt-4' not found
Error: Invalid model format

Causes:

Incorrect model format (should be provider/model)
Unsupported model
Missing provider API key

Solutions:

Correct model format:

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

Common models:

OpenAI: openai/gpt-5.4, openai/gpt-5-mini
Anthropic: anthropic/claude-sonnet-4-5, anthropic/claude-haiku-4-5, anthropic/claude-opus-4-6
Google: google/gemini-2.5-pro, google/gemini-2.5-flash

Use embedded docs to verify:

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

Debugging tips

Enable verbose logging

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

Check package versions

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

Validate TypeScript config

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

Getting help

Check embedded docs: Check embedded docs (see embedded-docs.md)
Search documentation: mastra.ai/docs
Check version compatibility: Ensure all @mastra packages are same version
File an issue: github.com/mastra-ai/mastra

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

What our scanner noticed· Low risk

Instructions that use the network
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Mastra

Publisher

Mastra (Official)

Source

mastra-ai/skills · skills/mastra · commit 3020257

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Mastra or Mastra.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download mastra.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Mastra

Mastra Framework Guide

Critical: Do not trust internal knowledge

Prerequisites

Resources

References

Scripts

Priority order for writing code

Core concepts

Mastra Studio

Mastra API CLI

Deploy to Mastra Platform

Mastra Factory

Reporting feedback

Critical requirements

TypeScript config

Model format

When you see errors

Development workflow

Files

references/common-errors.md

Common errors and troubleshooting

Quickstart

Build and configuration errors

"Cannot find module" or import errors

"Property X does not exist on type Y"

Agent errors

Agent not using assigned tools

Agent memory not persisting

Workflow errors

"Cannot read property 'then' of undefined"

Workflow state not updating

Memory errors

"Storage is required for Memory"

Semantic recall not working

Tool errors

"Tool validation failed"

Tool suspension not resuming

Storage errors

"Connection refused" or "Database does not exist"

Environment variable errors

"API key not found"

Model errors

"Model not found" or "Invalid model"

Debugging tips

Enable verbose logging

Check package versions

Validate TypeScript config

Getting help

Requirements and compatibility

Security

Attribution and licence

Related skills

Implement

Source Driven Development

Write Swift

Cardputer Buddy

Typescript Pro

Scala Pro

Download ZIP