{"record":{"id":"9140e1e91094238e","repo":"mastra-ai/mastra","slug":"agent-agentid-not-found-9140e1","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/network-route.ts","lineNumber":117,"sourceCode":"  options: NetworkStreamHandlerOptionsV6<UI_MESSAGE, OUTPUT>,\n): Promise<V6UIMessageStream<UI_MESSAGE>>;\nexport function handleNetworkStream<UI_MESSAGE extends V7UIMessage = V7UIMessage, OUTPUT = undefined>(\n  options: NetworkStreamHandlerOptionsV7<UI_MESSAGE, OUTPUT>,\n): Promise<V7UIMessageStream<UI_MESSAGE>>;\nexport async function handleNetworkStream<OUTPUT = undefined>({\n  mastra,\n  agentId,\n  agentVersion,\n  params,\n  defaultOptions,\n  version = 'v5',\n}: NetworkStreamHandlerOptions<SupportedUIMessage, OUTPUT>): Promise<SupportedUIMessageStream> {\n  const { messages, ...rest } = params;\n\n  const agentObj = agentVersion ? await mastra.getAgentById(agentId, agentVersion) : mastra.getAgentById(agentId);\n\n  if (!agentObj) {\n    throw new Error(`Agent ${agentId} not found`);\n  }\n\n  if (version === 'v7') {\n    const result = await agentObj.network<any>(messages as any, {\n      ...defaultOptions,\n      ...rest,\n    });\n\n    const stream = createUIMessageStreamV7<InternalUIMessageV7>({\n      originalMessages: messages as InternalUIMessageV7[],\n      execute: async ({ writer }) => {\n        for await (const part of toAISdkStream(result, { from: 'network', version: 'v7' })) {\n          writer.write(part);\n        }\n      },\n    });\n\n    return stream as unknown as SupportedUIMessageStream;","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/network-route.ts#L99-L135","documentation":"handleNetworkStream resolves the target agent via mastra.getAgentById before starting the network stream. If no agent with that ID exists (or the requested version does not), it throws 'Agent <id> not found' instead of streaming an error, so the HTTP request fails.","triggerScenarios":"POSTing to the network route with a body/param agentId that does not match any registered agent, or specifying an agentVersion that doesn't exist for that agent.","commonSituations":"Typos in agent IDs, agents removed or renamed in mastra config while clients still reference old IDs, per-environment registries differing (agent exists locally but not in prod), or draft/published version mismatch when using version options.","solutions":["Verify the agentId matches an agent registered on the Mastra instance (mastra.getAgentById in a REPL/log)","Check that the requested agentVersion (or versionId/status) exists for that agent","Ensure the route is hitting the environment where the agent is registered","If the agent should exist, confirm it is added to the Mastra instance's agents config"],"exampleFix":"// before\nconst res = await fetch('/api/network/agen-preview', {...})\n// after\nconst res = await fetch('/api/network/agent-preview', {...})","handlingStrategy":"validation","validationCode":"const agents = mastra.listAgents();\nconst id = 'agent-preview';\nif (!agents.some(a => a.id === id)) {\n  throw new Error(`Cannot call network: agent \"${id}\" is not registered`);\n}","typeGuard":"function agentExists(mastra: Mastra, id: string): boolean {\n  return Object.values(mastra.getAgents?.() ?? {}).some((a: any) => a.id === id || a.name === id);\n}","tryCatchPattern":"try {\n  const res = await fetch('/api/network/agent-preview', { method: 'POST', body });\n  if (!res.ok) throw new Error(await res.text());\n} catch (e) {\n  if (String(e.message).includes('not found')) {\n    console.error(`Agent not registered in this environment: ${e.message}`);\n  }\n}","preventionTips":["Centralize agent IDs in shared constants","Verify agent registration on boot (fail fast if a configured agent is missing)","Keep agent registries consistent across environments"],"tags":["http","agents","routing","configuration"],"backgroundTag":"agent-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}