Skip to main content

Upgrade to Mastra v1

This guide provides a comprehensive overview of breaking changes when upgrading from Mastra 0.x to v1.0. The migration is organized by package and feature area to help you systematically update your codebase.

Need help?

Need help with the migration? Join our Discord community to ask questions.

Migration Strategy​

Update all Mastra packages​

Use your package manager to update your project's versions. Be sure to update all Mastra packages at the same time to ensure compatibility.

Update Node.js version​

Mastra v1 requires Node.js 22.13.0 or higher. Update your development and production environments accordingly.

Breaking Changes by Area​

  • Mastra Class - Import restructuring and property access changes.
  • Agent Class - Voice methods moved to namespace and streaming API updates.
  • Tools - CreateTool execute signature changed to separate input and context.
  • Workflows - Function name changes and legacy features removed.
  • Memory - Configuration now requires explicit parameters and defaults changed.
  • Storage - Pagination standardized and methods renamed to list pattern.
  • Vectors - Vector store methods renamed to list pattern.
  • MCP - Tool context reorganized and deprecated client classes removed.
  • Tracing - OTEL telemetry replaced with dedicated observability package and exporters.
  • Evals & Scorers - Scorers API consolidated with new naming conventions.
  • CLI - Commands and flags removed for simpler interface.
  • Client SDKs - Types and utilities renamed for consistency.
  • Voice Packages - Packages renamed from speech to voice.

Migration Checklist​

Work through this checklist in order, starting with high-impact changes that affect most applications.

Codemod

We prepared automated codemods for you. Throughout the migration guide you'll find instructions on how to use them for specific changes.

If you want, you can run all v1 codemods at once:

npx @mastra/codemod@beta v1

High Impact Changes​

  • Update createTool tool signatures to (inputData, context) format - Tools
  • Restructure @mastra/core imports to use subpath imports - Mastra Class
  • Update pagination from offset/limit to page/perPage - Storage
  • Install @mastra/observability and wrap configuration with new Observability() - Tracing
  • Migrate from telemetry: to observability: configuration (if upgrading from 0.x OTEL) - Tracing

Medium Impact Changes​

  • Rename RuntimeContext to RequestContext throughout codebase - Agent Class, Tools, Workflows
  • Update storage methods from get* to list* pattern - Storage
  • Replace direct property access with getter methods - Mastra Class, Agent Class
  • Update memory scope if relying on default thread scope - Memory
  • Update vector store calls to use named arguments - Storage
  • Remove format parameter from agent methods - Agent Class
  • Update voice methods to use agent.voice namespace - Agent Class
  • Rename configuration property processors to spanOutputProcessors (if using custom processors) - Tracing

Low Impact Changes​

  • Rename createRunAsync to createRun - Workflows
  • Update voice package names from @mastra/speech-* to @mastra/voice-* - Voice Packages
  • Update scorer methods: runExperiment → runEvals, getScorerByName → getScorerById - Evals & Scorers
  • Remove deprecated CLI flags - CLI
  • Update client SDK types from Get* to List* - Client SDKs
  • Replace runCount with retryCount - Workflows
  • Update custom exporter method exportEvent to exportTracingEvent (if using custom exporters) - Tracing