{"record":{"id":"8a4a2af0504e05f9","repo":"mastra-ai/mastra","slug":"agent-not-found-8a4a2a","errorCode":null,"errorMessage":"Agent not found","messagePattern":"Agent not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/memory.ts","lineNumber":252,"sourceCode":"        try {\n          const subAgents = await ag.listAgents({ requestContext });\n\n          if (subAgents[agentId]) {\n            agent = subAgents[agentId];\n            break;\n          }\n        } catch (error) {\n          logger.debug('Error getting agent from agent', error);\n        }\n      }\n    }\n\n    if (!agent) {\n      if (allowMissingAgent) {\n        logger.debug('Agent not found in any resolution tier, returning null for storage fallback', { agentId });\n        return null;\n      }\n      throw new HTTPException(404, { message: 'Agent not found' });\n    }\n  }\n\n  if (agent) {\n    return await agent?.getMemory({\n      requestContext,\n    });\n  }\n}\n\n/**\n * Gets the storage from context, used as a fallback when agent memory can't be resolved.\n * This covers both cases where no agentId is provided and where the agentId refers to\n * a stored agent whose memory instance can't be hydrated (e.g. no editor configured).\n */\nfunction getStorageFromContext({ mastra }: Pick<MemoryContext, 'mastra'>): MastraStorage | undefined {\n  return mastra.getStorage();\n}","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/memory.ts#L234-L270","documentation":"Thrown by `getMemoryFromContext` when the given agentId cannot be resolved on the Mastra instance and the caller did not set `allowMissingAgent`. The handler needs the agent to obtain its Memory, so an unresolvable agent is a hard 404.","triggerScenarios":"Any memory route that resolves an agent (e.g. GET memory for agent) where `getAgentById`/agent lookup returns undefined: unknown agentId, agent registered under a different id, or agent missing on the deployed Mastra instance.","commonSituations":"Typo in agentId in the request; playground pointed at a Mastra instance without that agent; agents conditionally registered per environment; renamed agent after UI bookmarks stored the old id.","solutions":["Verify agentId against the agents actually registered on the Mastra instance (`mastra.getAgents()` keys).","Register the agent (or fix the registration condition) so it exists in the target environment.","Fix any typo/renamed id in the client or URL.","If a storage-fallback is acceptable without an agent, use the code path that passes `allowMissingAgent: true`."],"exampleFix":"// before\nconst mem = await getMemoryFromContext({ mastra, agentId: 'my-agnt' }) // 404\n// after\nconst mem = await getMemoryFromContext({ mastra, agentId: 'my-agent' })","handlingStrategy":"type-guard","validationCode":"const agents = mastra.getAgents?.() ?? {};\nif (!agents[agentId]) throw new Error(`Agent '${agentId}' not registered. Available: ${Object.keys(agents).join(', ')}`);","typeGuard":"function agentExists(mastra: Mastra, agentId: string): boolean {\n  return typeof mastra.getAgent === 'function' && !!mastra.getAgent(agentId);\n}","tryCatchPattern":"try {\n  const memory = await getMemoryFromContext({ mastra, agentId, requestContext });\n} catch (e) {\n  if (isHttpError(e, 404) && e.message === 'Agent not found') {\n    // fall back to default memory or surface a clear 'unknown agent' UI error\n  }\n  throw e;\n}","preventionTips":["List registered agents at startup and validate any user-supplied agentId against it.","Use typed constants for agent ids rather than free-form strings.","Keep agent registration unconditional across environments or gate consumers accordingly."],"tags":["memory","http-404","agent-resolution"],"backgroundTag":"agent-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}