{"record":{"id":"c15f38849086133a","repo":"mastra-ai/mastra","slug":"agent-with-id-agentid-not-found-c15f38","errorCode":null,"errorMessage":"Agent with id ${agentId} not found","messagePattern":"Agent with id (.+?) not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/agents.ts","lineNumber":976,"sourceCode":"        );\n      }\n    } catch (error) {\n      logger.debug('Error applying stored overrides to code agent', error);\n    }\n  }\n\n  // If still not found, try to get stored agent\n  if (!agent) {\n    logger.debug('Agent not found in code-defined agents, looking in stored agents', { agentId });\n    try {\n      agent = (await mastra.getEditor()?.agent.getById(agentId, versionOptions)) ?? null;\n    } catch (error) {\n      logger.debug('Error getting stored agent', error);\n    }\n  }\n\n  if (!agent) {\n    throw new HTTPException(404, { message: `Agent with id ${agentId} not found` });\n  }\n\n  return agent;\n}\n\nasync function formatAgent({\n  mastra,\n  agent,\n  requestContext,\n  isStudio,\n}: {\n  mastra: Context['mastra'];\n  agent: Agent;\n  requestContext: RequestContext;\n  isStudio: boolean;\n}): Promise<SerializedAgent> {\n  const description = agent.getDescription();\n  let metadata: Record<string, unknown> | undefined;","sourceCodeStart":958,"sourceCodeEnd":994,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/agents.ts#L958-L994","documentation":"Thrown by getAgentFromSystem after attempting to resolve the agent both from the in-memory Mastra registry (getAgentById) and from stored-agent storage. A 404 meaning no registered or stored agent exists with the given id in this Mastra instance.","triggerScenarios":"POSTing to /agents/:agentId/generate (or stream/legacy variants) where agentId was never registered via new Mastra({ agents: {...} }) and no stored-agent record exists; the agent was renamed/removed; connecting to a server/deployment that doesn't include that agent.","commonSituations":"Typos in agent ids in client code; agents registered conditionally (feature flags/env) so they're missing in some environments; tests hitting a Mastra instance with a different agent set than production; stale client config after agent deletion.","solutions":["Verify the agent is registered in the Mastra instance (mastra.getAgentById(agentId)) or exists as a stored agent in the configured storage","Fix the agentId typo or update the client to use the current agent id","List available agents (GET /api/agents) and pick the correct id","Check the server/deployment you are calling actually registers this agent (env/flag differences)"],"exampleFix":"// before\nnew Mastra({ agents: { weatherAgent } }); // client calls 'weather'\nawait mastraClient.getAgent('weather').generate({ messages });\n// after\nnew Mastra({ agents: { weather: weatherAgent } }); // id matches client\nawait mastraClient.getAgent('weather').generate({ messages });","handlingStrategy":"try-catch","validationCode":"// discover valid ids before calling\nconst { agents } = await fetch('/api/agents').then(r => r.json());\nif (!(agentId in agents)) {\n  throw new Error(`Agent '${agentId}' is not registered`);\n}","typeGuard":"function isRegisteredAgent(id: string, agents: Record<string, unknown>): id is keyof typeof agents & string {\n  return Object.prototype.hasOwnProperty.call(agents, id);\n}","tryCatchPattern":"try {\n  const res = await client.getAgent(agentId).generate({ messages });\n} catch (e) {\n  if (isHttpException(e, 404) && String(e.message).includes('not found')) {\n    // agent missing in this environment: list agents and warn about config drift\n  }\n}","preventionTips":["Centralize agent ids in a shared constant/enum used by server registration and clients","Verify agent registration in each environment (flags/env vars can gate registration)","After renaming/deleting an agent, grep clients and docs for the old id","Smoke-test against each deployment's GET /api/agents to catch drift"],"tags":["http-404","agents","rest-api","configuration"],"backgroundTag":"agent-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}