Upgrade to Mastra v1
In this guide you’ll learn how to upgrade through breaking changes in pre-v1 versions of Mastra. It’ll also help you upgrade to Mastra v1.
Use your package manager to update your project’s versions. Be sure to update all Mastra packages at the same time.
Versions mentioned in the headings refer to the @mastra/core package. If necessary, versions of other Mastra packages are called out in the detailed description.
All Mastra packages have a peer dependency on @mastra/core so your package manager can inform you about compatibility.
Migrate to v0.23 (unreleased)
This version isn’t released yet but we’re adding changes as we make them.
Migrate to v0.22
Deprecated: format: "aisdk"
The format: "aisdk" option in stream()/generate() methods is deprecated. Use the @mastra/ai-sdk package instead. Learn more in the Using Vercel AI SDK documentation.
Removed: MCP Classes
@mastra/mcp - 0.14.0
- Removed
MastraMCPClientclass. UseMCPClientclass instead. - Removed
MCPConfigurationOptionstype. UseMCPClientOptionstype instead. The API is identical. - Removed
MCPConfigurationclass. UseMCPClientclass instead.
Removed: CLI flags & commands
mastra - 0.17.0
- Removed the
mastra deployCLI command. Use the deploy instructions of your individual platform. - Removed
--envflag frommastra buildcommand. To start the build output with a custom env usemastra start --env <env>instead. - Remove
--portflag frommastra dev. Useserver.porton thenew Mastra()class instead.
Migrate to v0.21
No changes needed.