1# Common errors and troubleshooting
2 
3Comprehensive guide to common Mastra errors and their solutions.
4 
5## Quickstart
6 
7In a lot of cases, debugging errors can be greatly simplified by first checking the behavior in Mastra Studio. This allows you to interactively test agents and workflows, inspect logs, and see real-time error messages.
8 
9```bash
10npm run dev
11```
12 
13Open `http://localhost:4111` in your browser to access Mastra Studio.
14 
15## Build and configuration errors
16 
17### "Cannot find module" or import errors
18 
19**Symptoms**:
20 
21```bash
22Error: Cannot find module '@mastra/core'
23SyntaxError: Cannot use import statement outside a module
24```
25 
26**Causes**:
27 
28- CommonJS configuration in `tsconfig.json`
29- Missing `"type": "module"` in `package.json`
30- Incorrect module resolution
31 
32**Solutions**:
33 
341. Update `tsconfig.json`:
35 
36   ```json
37   {
38     "compilerOptions": {
39       "target": "ES2022",
40       "module": "ES2022",
41       "moduleResolution": "bundler"
42     }
43   }
44   ```
45 
462. Add to `package.json`:
47 
48   ```json
49   {
50     "type": "module"
51   }
52   ```
53 
543. Ensure imports use `.js` extensions for local files (if needed by your bundler)
55 
56### "Property X does not exist on type Y"
57 
58**Symptoms**:
59 
60```bash
61Property 'tools' does not exist on type 'Agent'
62Property 'memory' does not exist on type 'AgentConfig'
63```
64 
65**Causes**:
66 
67- Outdated API usage (Mastra is actively developed)
68- Incorrect import or type
69- Version mismatch between docs and installed package
70 
71**Solutions**:
72 
731. Check embedded docs (see `embedded-docs.md`) to check current API
742. Check `node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json` for current exports
753. Verify package versions: `npm list @mastra/core`
764. Update dependencies: `npm update @mastra/core`
77 
78## Agent errors
79 
80### Agent not using assigned tools
81 
82**Symptoms**:
83 
84- Agent responds "I don't have access to that tool"
85- Tools never get called despite being relevant
86 
87**Causes**:
88 
89- Tools not registered in Mastra instance
90- Tools not passed to Agent constructor
91- Tool IDs don't match
92 
93**Solutions**:
94 
95**Correct pattern**:
96 
97```typescript
98// 1. Create tool
99const weatherTool = createTool({
100  id: "get-weather",
101  // ... tool config
102});
103 
104// 2. Register in Mastra instance
105const mastra = new Mastra({
106  tools: {
107    weatherTool, // or 'weatherTool': weatherTool
108  },
109});
110 
111// 3. Assign to agent
112const agent = new Agent({
113  id: "weather-agent",
114  tools: { weatherTool }, // Reference the tool
115  // ... other config
116});
117```
118 
119**Alternative pattern (direct assignment)**:
120 
121```typescript
122const agent = new Agent({
123  id: "weather-agent",
124  tools: {
125    weatherTool: createTool({ id: "get-weather" /* ... */ }),
126  },
127});
128```
129 
130### Agent memory not persisting
131 
132**Symptoms**:
133 
134- Agent doesn't remember previous messages
135- Conversation history is lost between calls
136 
137**Causes**:
138 
139- No storage backend configured
140- Missing or inconsistent `threadId`
141- Memory not assigned to agent
142 
143**Solutions**:
144 
145```typescript
146// 1. Configure storage
147const storage = new PostgresStore({
148  connectionString: process.env.DATABASE_URL,
149});
150 
151// 2. Create memory with storage
152const memory = new Memory({
153  id: "chat-memory",
154  storage,
155  options: {
156    lastMessages: 10, // How many messages to retrieve
157  },
158});
159 
160// 3. Assign memory to agent
161const agent = new Agent({
162  id: "chat-agent",
163  memory,
164});
165 
166// 4. Use consistent threadId
167await agent.generate("Hello", {
168  threadId: "user-123-conversation", // Same threadId for entire conversation
169  resourceId: "user-123",
170});
171```
172 
173## Workflow errors
174 
175### "Cannot read property 'then' of undefined"
176 
177**Symptoms**:
178 
179```bash
180TypeError: Cannot read property 'then' of undefined
181Workflow execution fails immediately
182```
183 
184**Causes**:
185 
186- Forgot to call `.commit()` on workflow
187- Step returns undefined
188 
189**Solutions**:
190 
191**Correct pattern**:
192 
193```typescript
194const workflow = createWorkflow({
195  id: "my-workflow",
196  inputSchema: z.object({ data: z.string() }),
197  outputSchema: z.object({ result: z.string() }),
198})
199  .then(step1)
200  .then(step2)
201  .commit(); // REQUIRED!
202 
203// Then execute
204const run = await workflow.createRun();
205const result = await run.start({ inputData: { data: "test" } });
206```
207 
208### Workflow state not updating
209 
210**Symptoms**:
211 
212- State changes don't persist across steps
213- `getStepResult()` returns undefined
214 
215**Causes**:
216 
217- Not using `setState` to update state
218- Accessing state before step completes
219 
220**Solutions**:
221 
222```typescript
223const step1 = createStep({
224  id: "step1",
225  execute: async ({ state, setState }) => {
226    // Update state
227    await setState({ ...state, counter: (state.counter || 0) + 1 });
228    return { result: "done" };
229  },
230});
231 
232// Access state in subsequent steps
233const step2 = createStep({
234  id: "step2",
235  execute: async ({ state }) => {
236    console.log(state.counter); // Access updated state
237    return { result: "complete" };
238  },
239});
240```
241 
242## Memory errors
243 
244### "Storage is required for Memory"
245 
246**Symptoms**:
247 
248```bash
249Error: Storage is required for Memory
250Memory instantiation fails
251```
252 
253**Causes**:
254 
255- Memory created without storage backend
256 
257**Solutions**:
258 
259```typescript
260// Always provide storage when creating Memory
261const memory = new Memory({
262  id: "my-memory",
263  storage: postgresStore, // REQUIRED
264  options: {
265    lastMessages: 10,
266  },
267});
268```
269 
270### Semantic recall not working
271 
272**Symptoms**:
273 
274- Memory doesn't retrieve semantically similar messages
275- Only recent messages are returned
276 
277**Causes**:
278 
279- No vector store configured
280- No embedder configured
281- `semanticRecall` not enabled
282 
283**Solutions**:
284 
285```typescript
286const memory = new Memory({
287  id: "semantic-memory",
288  storage: postgresStore,
289  vector: chromaVectorStore, // REQUIRED for semantic recall
290  embedder: openaiEmbedder, // REQUIRED for semantic recall
291  options: {
292    lastMessages: 10,
293    semanticRecall: true, // REQUIRED
294  },
295});
296```
297 
298## Tool errors
299 
300### "Tool validation failed"
301 
302**Symptoms**:
303 
304```bash
305Error: Input validation failed for tool 'my-tool'
306ZodError: Expected string, received number
307```
308 
309**Causes**:
310 
311- Input doesn't match inputSchema
312- Missing required fields
313- Type mismatch
314 
315**Solutions**:
316 
317```typescript
318const tool = createTool({
319  id: "my-tool",
320  inputSchema: z.object({
321    name: z.string(),
322    age: z.number().optional(), // Make optional fields explicit
323  }),
324  execute: async (input) => {
325    // input is validated and typed
326    return { result: `Hello ${input.name}` };
327  },
328});
329 
330// Correct usage
331await tool.execute({ name: "Alice" }); // Works
332await tool.execute({ name: "Bob", age: 30 }); // Works
333await tool.execute({ age: 30 }); // ERROR: name is required
334```
335 
336### Tool suspension not resuming
337 
338**Symptoms**:
339 
340- Tool suspends but never resumes
341- resumeData is undefined
342 
343**Causes**:
344 
345- Not calling workflow.resume() or agent.generate() with resumeData
346- Incorrect resumeSchema
347 
348**Solutions**:
349 
350```typescript
351const approvalTool = createTool({
352  id: "approval",
353  inputSchema: z.object({ request: z.string() }),
354  outputSchema: z.object({ approved: z.boolean() }),
355  suspendSchema: z.object({ requestId: z.string() }),
356  resumeSchema: z.object({ approved: z.boolean() }),
357  execute: async (input, context) => {
358    if (!context.resumeData) {
359      // First call - suspend
360      const requestId = generateId();
361      context.suspend({ requestId });
362      return; // Execution pauses here
363    }
364 
365    // Resumed - use resumeData
366    return { approved: context.resumeData.approved };
367  },
368});
369 
370// Resume the workflow/agent
371await run.resume({
372  resumeData: { approved: true },
373});
374```
375 
376## Storage errors
377 
378### "Connection refused" or "Database does not exist"
379 
380**Symptoms**:
381 
382```bash
383Error: connect ECONNREFUSED 127.0.0.1:5432
384Error: database "mastra" does not exist
385```
386 
387**Causes**:
388 
389- Database not running
390- Incorrect connection string
391- Database not created
392 
393**Solutions**:
394 
3951. Start database (Postgres example):
396 
397```bash
398docker run -d \
399  --name mastra-postgres \
400  -e POSTGRES_PASSWORD=password \
401  -e POSTGRES_DB=mastra \
402  -p 5432:5432 \
403  postgres:16
404```
405 
4062. Verify connection string:
407 
408```env
409DATABASE_URL=postgresql://postgres:password@localhost:5432/mastra
410```
411 
4123. Initialize storage:
413 
414```typescript
415const storage = new PostgresStore({
416  connectionString: process.env.DATABASE_URL,
417});
418await storage.init(); // Creates tables if needed
419```
420 
421## Environment variable errors
422 
423### "API key not found"
424 
425**Symptoms**:
426 
427```bash
428Error: OPENAI_API_KEY environment variable is not set
429401 Unauthorized
430```
431 
432**Causes**:
433 
434- Missing .env file
435- Environment variables not loaded
436- Incorrect variable name
437 
438**Solutions**:
439 
4401. Create .env file:
441 
442```env
443OPENAI_API_KEY=sk-...
444ANTHROPIC_API_KEY=sk-ant-...
445GOOGLE_GENERATIVE_AI_API_KEY=...
446```
447 
4482. Load environment variables (for Node.js):
449 
450```typescript
451import "dotenv/config"; // At top of entry file
452```
453 
4543. Verify variable is loaded:
455 
456```typescript
457if (!process.env.OPENAI_API_KEY) {
458  throw new Error("OPENAI_API_KEY is required");
459}
460```
461 
462## Model errors
463 
464### "Model not found" or "Invalid model"
465 
466**Symptoms**:
467 
468```bash
469Error: Model 'gpt-4' not found
470Error: Invalid model format
471```
472 
473**Causes**:
474 
475- Incorrect model format (should be `provider/model`)
476- Unsupported model
477- Missing provider API key
478 
479**Solutions**:
480 
481**Correct model format**:
482 
483```typescript
484const agent = new Agent({
485  model: "openai/gpt-5.4", // ✅ Correct
486  // NOT: model: 'gpt-5.4'       // ❌ Missing provider
487});
488```
489 
490**Common models**:
491 
492- OpenAI: `openai/gpt-5.4`, `openai/gpt-5-mini`
493- Anthropic: `anthropic/claude-sonnet-4-5`, `anthropic/claude-haiku-4-5`, `anthropic/claude-opus-4-6`
494- Google: `google/gemini-2.5-pro`, `google/gemini-2.5-flash`
495 
496**Use embedded docs to verify**:
497 
498```bash
499# Check supported models
500ls node_modules/@mastra/core/dist/docs/
501# See embedded-docs.md for lookup instructions
502```
503 
504## Debugging tips
505 
506### Enable verbose logging
507 
508```typescript
509const mastra = new Mastra({
510  logger: new PinoLogger({
511    name: "mastra",
512    level: "debug", // or 'trace' for even more detail
513  }),
514});
515```
516 
517### Check package versions
518 
519```bash
520npm list @mastra/core
521npm list @mastra/memory
522npm list @mastra/rag
523```
524 
525### Validate TypeScript config
526 
527```bash
528npx tsc --showConfig
529# Verify target: ES2022, module: ES2022
530```
531 
532## Getting help
533 
5341. **Check embedded docs**: Check embedded docs (see `embedded-docs.md`)
5352. **Search documentation**: [mastra.ai/docs](https://mastra.ai/docs)
5363. **Check version compatibility**: Ensure all @mastra packages are same version
5374. **File an issue**: [github.com/mastra-ai/mastra](https://github.com/mastra-ai/mastra)
538