Setting the file. One moment.
Subchapter 2.6
references/migration-guide.mdMarkdown5 KBView on GitHub
Guide for upgrading Mastra versions using official documentation and current API verification.
For version upgrades, follow this process:
Always start with the official migration documentation: https://mastra.ai/llms.txt
Look for the Migrations or Guides section, which will have:
Example sections to look for:
/guides/migrations/upgrade-to-v1//guides/migrations/upgrade-to-v2/After identifying breaking changes, verify the new APIs:
Check your installed version:
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"ApiName"'
cat node_modules/@mastra/core/dist/[path-from-source-map]See embedded-docs.md for detailed lookup instructions.
If packages aren’t updated yet, check what APIs will look like: https://mastra.ai/reference/[topic]
See remote-docs.md for detailed lookup instructions.
# 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 testCheck official migration docs: https://mastra.ai/guides/migrations/upgrade-to-v1/overview.md
This will list:
For each breaking change:
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"NewApi"'
cat node_modules/@mastra/core/dist/[path]Official docs say: “Tool execute signature changed”
Look up current signature:
cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"createTool"'
cat node_modules/@mastra/core/dist/tools/tool.d.tsUpdate based on type definition:
// Old (from docs)
execute: async (input) => { ... }
// New (from embedded docs)
execute: async (inputData, context) => { ... }https://mastra.ai/llms.txtnpm list @mastra/corenpx tsc --noEmitnpm testnpm run dev| Resource | Use For |
|---|---|
https://mastra.ai/llms.txt | Finding migration guides and breaking changes |
embedded-docs.md | Looking up new API signatures after updating |
remote-docs.md | Checking latest docs before updating |
common-errors.md | Fixing migration errors |
Always update all @mastra packages together
npm install @mastra/core@latest @mastra/memory@latest @mastra/rag@latest mastra@latestCheck for automated migration tools
npx @mastra/codemod@latest [version]Verify Node.js version requirements
Run database migrations if using storage
https://mastra.ai/llms.txt → Migrations sectionembedded-docs.mdcommon-errors.mdhttps://mastra.ai/llms.txt