{"record":{"id":"023a85bec23cd01b","repo":"mastra-ai/mastra","slug":"path-must-include-agentid-to-route-to-the-correct","errorCode":null,"errorMessage":"Path must include :agentId to route to the correct agent or pass the agent explicitly","messagePattern":"Path must include :agentId to route to the correct agent or pass the agent explicitly","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/ai-sdk/src/chat-route.ts","lineNumber":546,"sourceCode":" * - Request context from the incoming request overrides `defaultOptions.requestContext` if both are present\n */\nexport function chatRoute<OUTPUT = undefined, UI_MESSAGE extends SupportedUIMessage = SupportedUIMessage>({\n  path = '/chat/:agentId',\n  agent,\n  defaultOptions,\n  experimentalTransform,\n  version = 'v5',\n  agentVersion,\n  sendStart = true,\n  sendFinish = true,\n  sendReasoning = false,\n  sendSources = false,\n  heartbeatMs,\n  onError,\n  messageMetadata,\n}: chatRouteOptions<OUTPUT, UI_MESSAGE>): ReturnType<typeof registerApiRoute> {\n  if (!agent && !path.includes('/:agentId')) {\n    throw new Error('Path must include :agentId to route to the correct agent or pass the agent explicitly');\n  }\n  assertValidHeartbeatMs(heartbeatMs);\n\n  return registerApiRoute(path, {\n    method: 'POST',\n    openapi: {\n      summary: 'Chat with an agent',\n      description: 'Send messages to an agent and stream the response in the AI SDK format',\n      tags: ['ai-sdk'],\n      parameters: [\n        {\n          name: 'agentId',\n          in: 'path',\n          required: true,\n          description: 'The ID of the agent to chat with',\n          schema: {\n            type: 'string',\n          },","sourceCodeStart":528,"sourceCodeEnd":564,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/chat-route.ts#L528-L564","documentation":"chatRoute() can either serve a fixed agent (passed via the agent option) or resolve the agent dynamically from the URL. Dynamic resolution requires the path template to contain the :agentId param. If neither an explicit agent nor the :agentId param exists, the route cannot know which agent to run, so it throws at registration time (fail fast, before serving requests).","triggerScenarios":"Calling chatRoute({ path: '/api/chat' }) without an agent option and without ':agentId' in the path string; renaming the path segment from ':agentId' to something like ':agentSlug' which the library doesn't recognize.","commonSituations":"Setting up a single-agent endpoint and forgetting the explicit agent option; copy-pasting a multi-agent path template and simplifying it while removing the agent option; typos like ':agentid' (wrong case).","solutions":["Pass the agent explicitly: chatRoute({ agent: myAgent, path: '/api/chat' })","Or include the param in the path: chatRoute({ path: '/api/chat/:agentId' })","Ensure the param is spelled exactly ':agentId'","If using another param name, rename it to ':agentId' or supply the agent option"],"exampleFix":"// before\nchatRoute({ path: '/api/chat' })\n// after\nchatRoute({ path: '/api/chat/:agentId' })\n// or\nchatRoute({ path: '/api/chat', agent: myAgent })","handlingStrategy":"validation","validationCode":"if (!agent && !path.includes('/:agentId')) {\n  throw new Error('chatRoute requires an explicit agent or a path containing :agentId');\n}","typeGuard":"function chatRouteConfigIsValid(cfg: { agent?: unknown; path: string }): boolean {\n  return cfg.agent != null || cfg.path.includes('/:agentId');\n}","tryCatchPattern":"try {\n  const route = chatRoute({ path });\n} catch (err) {\n  if (err instanceof Error && err.message.includes(':agentId')) {\n    console.error('Fix chatRoute config: pass agent or use path /:agentId');\n  }\n}","preventionTips":["Decide up front: fixed-agent route (pass agent) vs multi-agent route (use :agentId)","Spell the param exactly ':agentId' — case-sensitive","Add a unit test that registers all routes at module load so config errors surface in CI","When simplifying copied route templates, keep the agent option or the param"],"tags":["ai-sdk","configuration","routing","developer-error"],"backgroundTag":"invalid-route-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}