{"record":{"id":"d2d0a332b1f38411","repo":"mastra-ai/mastra","slug":"mastra-instance-is-required-for-conversations","errorCode":null,"errorMessage":"Mastra instance is required for conversations","messagePattern":"Mastra instance is required for conversations","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"critical","filePath":"packages/server/src/server/handlers/conversations.ts","lineNumber":59,"sourceCode":"    deleted: true,\n  };\n}\n\nexport const CREATE_CONVERSATION_ROUTE = createRoute({\n  method: 'POST',\n  path: '/v1/conversations',\n  responseType: 'json',\n  bodySchema: createConversationBodySchema,\n  responseSchema: conversationObjectSchema,\n  summary: 'Create a conversation',\n  description: 'Creates a new thread-backed conversation for agent-backed Responses API requests',\n  tags: ['Responses'],\n  requiresAuth: true,\n  requiresPermission: MastraFGAPermissions.AGENTS_CREATE,\n  handler: async ({ mastra, requestContext, agent_id, conversation_id, resource_id, title, metadata }) => {\n    try {\n      if (!mastra) {\n        throw new HTTPException(500, { message: 'Mastra instance is required for conversations' });\n      }\n\n      const agent = await getAgentFromSystem({ mastra, agentId: agent_id });\n      const memory = await agent.getMemory({ requestContext });\n      if (!memory) {\n        throw new HTTPException(400, { message: `Agent \"${agent.id}\" does not have memory configured` });\n      }\n      if (!(await getAgentMemoryStore({ agent, requestContext }))) {\n        throw new HTTPException(400, { message: `Memory storage is not configured for agent \"${agent.id}\"` });\n      }\n\n      const threadId = conversation_id ?? randomUUID();\n      const resourceId = getEffectiveResourceId(requestContext, resource_id) ?? threadId;\n      const thread = await memory.createThread({\n        threadId,\n        resourceId,\n        title,\n        metadata,","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/conversations.ts#L41-L77","documentation":"This is an internal server misconfiguration guard: the create-conversation route handler requires the Mastra instance from the server DI context, and throws HTTP 500 when it is undefined. Since Mastra is normally injected by the server runtime, a missing instance means the server was started without a Mastra instance or the handler context was built incorrectly.","triggerScenarios":"POSTing to the conversations (Responses) route when the `mastra` value on the handler context is undefined — server constructed without a Mastra instance, custom server embedding that omits mastra in context, or broken DI wiring in a self-hosted/Hono mount.","commonSituations":"Embedding the Mastra server handlers in a custom Hono app and forgetting to pass the Mastra instance into the context; server bootstrap failure where mastra is not registered; deploying a build where the mastra initialization module was tree-shaken or failed silently.","solutions":["Ensure the server is created with a Mastra instance (pass it to the server constructor / context binding) and restart","If mounting handlers manually, set mastra on the request context exactly as the generated server does","Check server startup logs for Mastra initialization errors and fix the underlying init failure","Verify the deployment includes the mastra instance module and it is not stripped by the bundler"],"exampleFix":"// before\nconst app = createServerRoutes({}); // mastra missing\n// after\nconst mastra = new Mastra({ agents: { myAgent } });\nconst app = createServerRoutes({ mastra });","handlingStrategy":"validation","validationCode":"// at server bootstrap\nif (!mastra) {\n  throw new Error('Server misconfigured: Mastra instance was not provided to the server context');\n}","typeGuard":"function hasMastra(ctx: { mastra?: unknown }): ctx is { mastra: Mastra } {\n  return !!ctx.mastra && typeof (ctx.mastra as Mastra).getAgents === 'function';\n}","tryCatchPattern":"try {\n  const conv = await client.createConversation({ agent_id, resource_id });\n} catch (e) {\n  if (e.status === 500 && /Mastra instance is required/.test(e.message)) {\n    // server-side DI bug: alert/fix server bootstrap, not the request\n  }\n  throw e;\n}","preventionTips":["Always construct the server with a Mastra instance","Smoke-test conversation creation right after deployment","If embedding handlers manually, mirror the generated server's context wiring","Watch startup logs for Mastra init failures"],"tags":["server","http-500","configuration","di-wiring"],"backgroundTag":"missing-mastra-instance","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}