Upgrade to Mastra v1

:::info[Update to latest 0.x version] Before upgrading to v1, make sure you've updated to the latest 0.x version of Mastra. Follow the upgrade to latest 0.x guide first, then return here to complete the v1 migration. :::

Mastra v1 was released in January 2026. We recommend starting any new projects with Mastra v1, or upgrading your existing project to continue receiving updates and support.

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.

:::tip[Need help?] Need help with the migration? Join our Discord community to ask questions. :::

Migration strategy

Update all Mastra packages to latest tag

Use your package manager to update your project's versions. Be sure to update all Mastra packages at the same time to ensure compatibility (all @mastra/* packages and mastra).

Here's how you update the most commonly used packages:

npm install @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest

Install any other Mastra package with the @latest tag and you'll get the latest v1 version available. Be sure to update all Mastra packages (especially if you're in a monorepo) to avoid version mismatches.

Update Node.js version

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

Go through migration checklist

Work through the migration checklist below to update your codebase. Each item links to a detailed guide for that specific change.

:::info[Codemods]

We prepared automated codemods for you. If you want, you can run all v1 codemods at once:

npx @mastra/codemod@latest v1

:::

:::note[Database Migration Required]

If you're using PostgreSQL or LibSQL storage, you'll need to run a database migration. See the Storage migration guide for details.

:::

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.
• RAG - Parameter naming updated for clarity.
• 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.
• Deployment - CloudflareDeployer configuration updated to use standard wrangler.json property names.
• 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.

:::info[Codemods]

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@latest 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 keepSeparator to separatorPosition in chunk options - RAG
• 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