{"record":{"id":"fcf75b25c2346157","repo":"mastra-ai/mastra","slug":"mastra-instance-is-required-for-agent-backed-respo","errorCode":null,"errorMessage":"Mastra instance is required for agent-backed responses","messagePattern":"Mastra instance is required for agent-backed responses","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"packages/server/src/server/handlers/responses.ts","lineNumber":307,"sourceCode":"\n/**\n * Resolves the registered Mastra agent that owns the response request.\n */\nasync function resolveResponseAgent({\n  mastra,\n  agentId,\n}: {\n  mastra: Mastra | undefined;\n  agentId?: string;\n}): Promise<Agent<any, any, any, any>> {\n  if (!agentId) {\n    throw new HTTPException(400, {\n      message: 'Responses requests require an agent_id',\n    });\n  }\n\n  if (!mastra) {\n    throw new HTTPException(500, { message: 'Mastra instance is required for agent-backed responses' });\n  }\n\n  return getAgentFromSystem({ mastra, agentId });\n}\n\nasync function resolveAgentMemoryStore({\n  agent,\n  requestContext,\n  errorMessage,\n}: {\n  agent: Agent<any, any, any, any>;\n  requestContext: RequestContext;\n  errorMessage: string;\n}): Promise<MemoryStorage> {\n  const agentMemoryStore = await getAgentMemoryStore({ agent, requestContext });\n  if (!agentMemoryStore) {\n    throw new HTTPException(400, { message: errorMessage });\n  }","sourceCodeStart":289,"sourceCodeEnd":325,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/responses.ts#L289-L325","documentation":"Resolving an agent requires the Mastra instance to be available on the server. When resolveResponseAgent is called with mastra undefined, it throws this 500 because agent lookup (getAgentFromSystem) is impossible without it. This indicates a server wiring problem, not a client mistake.","triggerScenarios":"POST /api/responses reaching the handler while the Mastra instance failed to initialize or was not injected into the handler context (e.g., misconfigured server bootstrap, HMR/dev teardown leaving mastra undefined).","commonSituations":"Custom server setups not passing mastra to the route handlers; plugin/middleware ordering issues; broken mastra build/registration so the instance never registers; test harnesses invoking handlers without a mastra instance.","solutions":["Fix server bootstrap so the Mastra instance is constructed and passed to the responses handlers","Ensure agents are registered in the Mastra instance (agents map) before serving requests","Check for initialization errors earlier in server startup logs","If using a custom deployment, use the standard mastra dev/server wiring that injects mastra"],"exampleFix":"// before\ncreateHandler({ mastra: undefined });\n// after\nimport { mastra } from './mastra';\ncreateHandler({ mastra });","handlingStrategy":"try-catch","validationCode":"if (!mastra) throw new Error('Mastra instance missing from handler context');","typeGuard":"function hasMastra(ctx) { return ctx != null && typeof ctx.mastra === 'object'; }","tryCatchPattern":"try {\n  await callResponsesApi(payload);\n} catch (e) {\n  if (e?.status === 500 && /Mastra instance is required/.test(e.message)) {\n    // server misconfiguration: report to ops, do not retry\n  }\n  throw e;\n}","preventionTips":["Use standard mastra server bootstrap so mastra is injected into handlers","Add a startup check that the Mastra instance is constructed and agents are registered","Cover handler wiring in an integration test"],"tags":["server","http-500","initialization","responses-api"],"backgroundTag":"server-not-initialized","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}