1# Migration Guide
2 
3Guide for upgrading Mastra versions using official documentation and current API verification.
4 
5## Migration strategy
6 
7For version upgrades, follow this process:
8 
9### 1. Check official migration docs
10 
11**Always start with the official migration documentation:** `https://mastra.ai/llms.txt`
12 
13Look for the **Migrations** or **Guides** section, which will have:
14 
15- Breaking changes for each version
16- Automated migration tools
17- Step-by-step upgrade instructions
18 
19**Example sections to look for:**
20 
21- `/guides/migrations/upgrade-to-v1/`
22- `/guides/migrations/upgrade-to-v2/`
23- Breaking changes lists
24 
25### 2. Use embedded docs for current APIs
26 
27After identifying breaking changes, verify the new APIs:
28 
29**Check your installed version:**
30 
31```bash
32cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"ApiName"'
33cat node_modules/@mastra/core/dist/[path-from-source-map]
34```
35 
36See [`embedded-docs.md`](embedded-docs.md) for detailed lookup instructions.
37 
38### 3. Use remote docs for latest info
39 
40If packages aren't updated yet, check what APIs will look like: `https://mastra.ai/reference/[topic]`
41 
42See [`remote-docs.md`](remote-docs.md) for detailed lookup instructions.
43 
44## Quick migration workflow
45 
46```bash
47# 1. Check current version
48npm list @mastra/core
49 
50# 2. Fetch migration guide from official docs
51# Use WebFetch: https://mastra.ai/llms.txt
52# Find relevant migration section
53 
54# 3. Update dependencies
55npm install @mastra/core@latest @mastra/memory@latest @mastra/rag@latest mastra@latest
56 
57# 4. Run automated migration (if available)
58npx @mastra/codemod@latest v1  # or whatever version
59 
60# 5. Check embedded docs for new APIs
61cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json
62 
63# 6. Fix breaking changes using embedded docs lookup
64# See embedded-docs.md for how to look up each API
65 
66# 7. Test
67npm run dev
68npm test
69```
70 
71## Common migration patterns
72 
73### Finding what changed
74 
75**Check official migration docs:** `https://mastra.ai/guides/migrations/upgrade-to-v1/overview.md`
76 
77This will list:
78 
79- Breaking changes
80- Deprecated APIs
81- New features
82- Migration tools
83 
84### Updating API usage
85 
86**For each breaking change:**
87 
881. **Find the old API** in your code
892. **Look up the new API** using embedded docs:
90   ```bash
91   cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"NewApi"'
92   cat node_modules/@mastra/core/dist/[path]
93   ```
943. **Update your code** based on the type signatures
954. **Test** the change
96 
97### Example: Tool execute signature change
98 
99**Official docs say:** "Tool execute signature changed"
100 
101**Look up current signature:**
102 
103```bash
104cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"createTool"'
105cat node_modules/@mastra/core/dist/tools/tool.d.ts
106```
107 
108**Update based on type definition:**
109 
110```typescript
111// Old (from docs)
112execute: async (input) => { ... }
113 
114// New (from embedded docs)
115execute: async (inputData, context) => { ... }
116```
117 
118## Pre-migration checklist
119 
120- [ ] Backup code (git commit)
121- [ ] Check official migration docs: `https://mastra.ai/llms.txt`
122- [ ] Note current version: `npm list @mastra/core`
123- [ ] Read breaking changes list
124- [ ] Tests are passing
125 
126## Post-migration checklist
127 
128- [ ] All dependencies updated together
129- [ ] TypeScript compiles: `npx tsc --noEmit`
130- [ ] Tests pass: `npm test`
131- [ ] Studio works: `npm run dev`
132- [ ] No console warnings
133- [ ] APIs verified against embedded docs
134 
135## Migration resources
136 
137| Resource                               | Use For                                       |
138| -------------------------------------- | --------------------------------------------- |
139| `https://mastra.ai/llms.txt`           | Finding migration guides and breaking changes |
140| [`embedded-docs.md`](embedded-docs.md) | Looking up new API signatures after updating  |
141| [`remote-docs.md`](remote-docs.md)     | Checking latest docs before updating          |
142| [`common-errors.md`](common-errors.md) | Fixing migration errors                       |
143 
144## Version-specific notes
145 
146### General principles
147 
1481. **Always update all @mastra packages together**
149 
150   ```bash
151   npm install @mastra/core@latest @mastra/memory@latest @mastra/rag@latest mastra@latest
152   ```
153 
1542. **Check for automated migration tools**
155 
156   ```bash
157   npx @mastra/codemod@latest [version]
158   ```
159 
1603. **Verify Node.js version requirements**
161   - Check official migration docs for minimum Node version
162 
1634. **Run database migrations if using storage**
164   - Follow storage migration guide in official docs
165 
166## Getting help
167 
1681. **Check official migration docs**: `https://mastra.ai/llms.txt` → Migrations section
1692. **Look up new APIs**: See [`embedded-docs.md`](embedded-docs.md)
1703. **Check for errors**: See [`common-errors.md`](common-errors.md)
1714. **Ask in Discord**: https://discord.gg/BTYqqHKUrf
1725. **File issues**: https://github.com/mastra-ai/mastra/issues
173 
174## Key principles
175 
1761. **Official docs are source of truth** - Start with `https://mastra.ai/llms.txt`
1772. **Verify with embedded docs** - Check installed version APIs
1783. **Update incrementally** - Don't skip major versions
1794. **Test thoroughly** - Run tests after each change
1805. **Use automation** - Use codemods when available
181