{"record":{"id":"2f0dc17d10dd0ff5","repo":"mastra-ai/mastra","slug":"agent-agentid-not-found-2f0dc1","errorCode":null,"errorMessage":"Agent ${agentId} not found","messagePattern":"Agent (.+?) not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/ai-sdk/src/chat-route.ts","lineNumber":303,"sourceCode":"  version = 'v5',\n  sendStart = true,\n  sendFinish = true,\n  sendReasoning = false,\n  sendSources = false,\n  onError,\n  messageMetadata,\n}: Omit<ChatStreamHandlerOptions<any, OUTPUT>, 'messageMetadata'> & {\n  messageMetadata?: any;\n}): Promise<ReadableStream<any>> {\n  const { messages, resumeData, runId, requestContext, trigger, ...rest } = params;\n\n  if (resumeData && !runId) {\n    throw new Error('runId is required when resumeData is provided');\n  }\n\n  const baseAgent = mastra.getAgentById(agentId);\n  if (!baseAgent) {\n    throw new Error(`Agent ${agentId} not found`);\n  }\n\n  // When an editor is configured, an agent's runtime config (instructions, tools,\n  // model, ...) can live in stored config rather than the code definition. Studio\n  // resolves these stored overrides before every run, so this endpoint must do the\n  // same or it would execute a stale/empty code-defined agent (issue #18574). An\n  // explicit agentVersion (from query params or route options) wins; otherwise we\n  // default to the published version, matching the built-in agent handlers.\n  let agentObj = baseAgent;\n  const editorAgent = mastra.getEditor?.()?.agent;\n  if (editorAgent) {\n    agentObj = await editorAgent.applyStoredOverrides(\n      baseAgent,\n      agentVersion ?? { status: 'published' },\n      requestContext as RequestContext | undefined,\n    );\n  } else if (agentVersion) {\n    // No editor configured: preserve the prior behavior of surfacing the","sourceCodeStart":285,"sourceCodeEnd":321,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/chat-route.ts#L285-L321","documentation":"handleChatStream resolves the agent via mastra.getAgentById(agentId) before streaming. If no agent with that ID is registered on the Mastra instance, the handler throws. With an editor configured, a second lookup path also resolves stored config overrides, but the code-level registration must exist or be resolvable first.","triggerScenarios":"POSTing to the chat route with an :agentId (or explicit agent option) that does not match any agent registered on the Mastra instance; agent renamed/removed in code while the client still references the old ID.","commonSituations":"Typos in the agent ID on the frontend; agents registered conditionally so they are absent in some environments; refactoring that renamed agents without updating client code; requesting a versioned agent whose base definition is gone.","solutions":["Verify the agent ID matches mastra.getAgent({ name }) / agent registration exactly","Log or list all registered agents (Object.keys of the agents config) and compare with the requested ID","Ensure the agent is registered unconditionally in the environment handling the request","Update frontend constants/config to the renamed agent ID after refactors"],"exampleFix":"// before\nuseChat({ api: '/api/chat/my-agnt' })\n// after\nuseChat({ api: '/api/chat/my-agent' }) // must match the registered agent ID","handlingStrategy":"validation","validationCode":"const agents = mastra.getAgents?.() ?? {};\nif (!(agentId in agents)) {\n  throw new Error(`Unknown agentId \"${agentId}\". Available: ${Object.keys(agents).join(', ')}`);\n}","typeGuard":"function agentExists(mastra: Mastra, agentId: string): boolean {\n  return mastra.getAgentById(agentId) != null;\n}","tryCatchPattern":"try {\n  const stream = await handleChatStream({ mastra, agentId, ...params });\n} catch (err) {\n  if (err instanceof Error && /Agent .* not found/.test(err.message)) {\n    return new Response(JSON.stringify({ error: 'UNKNOWN_AGENT', agentId }), { status: 404 });\n  }\n  throw err;\n}","preventionTips":["Keep agent IDs in a shared constants module used by both server registration and client calls","List registered agents when a 404-type agent error occurs to surface mismatches","Avoid conditional agent registration that differs between environments","Grep/rename-check agent IDs during refactors"],"tags":["ai-sdk","agent-not-found","configuration","routing"],"backgroundTag":"agent-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}