{"record":{"id":"ee3c71c864e0d178","repo":"mastra-ai/mastra","slug":"path-must-include-agentid-to-route-to-the-correct-ee3c71","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/network-route.ts","lineNumber":223,"sourceCode":" * @example\n * // Fixed agent with custom path\n * networkRoute({\n *   path: '/api/orchestrator',\n *   agent: 'router-agent',\n *   defaultOptions: {\n *     maxSteps: 10,\n *   },\n * });\n */\nexport function networkRoute<OUTPUT = undefined>({\n  path = '/network/:agentId',\n  agent,\n  defaultOptions,\n  version = 'v5',\n  agentVersion,\n}: NetworkRouteOptions<OUTPUT>): 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\n  return registerApiRoute(path, {\n    method: 'POST',\n    openapi: {\n      summary: 'Execute an agent network and stream AI SDK events',\n      description: 'Routes a request to an agent network and streams UIMessage chunks in 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 routing agent to execute as a network',\n          schema: { type: 'string' },\n        },\n        {\n          name: 'versionId',","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/network-route.ts#L205-L241","documentation":"networkRoute can either bind to a fixed agent passed via options, or dynamically select the agent from the URL. If neither is possible — no explicit agent option and the path lacks the :agentId parameter — the route would have no way to know which agent to run, so it throws at registration time.","triggerScenarios":"Calling networkRoute({ path: '/api/network' }) without an `agent` option and without '/:agentId' in the path.","commonSituations":"Copy-pasting route setup that previously included /:agentId and simplifying the path; forgetting to pass the agent when hardcoding a route; upgrading Mastra where this validation became stricter.","solutions":["Add :agentId to the path, e.g. '/api/network/:agentId'","Or pass the agent explicitly: networkRoute({ path: '/api/network', agent: myAgent })","Re-check route registration code after refactors of server routes"],"exampleFix":"// before\nnetworkRoute({ path: '/api/network', mastra })\n// after\nnetworkRoute({ path: '/api/network/:agentId', mastra })\n// or\nnetworkRoute({ path: '/api/network', agent: myAgent, mastra })","handlingStrategy":"validation","validationCode":"function assertNetworkRouteOptions(path: string, opts: { agent?: unknown }) {\n  if (!opts.agent && !path.includes('/:agentId')) {\n    throw new Error('networkRoute requires an explicit agent or a path containing :agentId');\n  }\n}\nassertNetworkRouteOptions('/api/network', {});","typeGuard":"null","tryCatchPattern":"try {\n  networkRoute({ path, mastra });\n} catch (e) {\n  if (String(e.message).includes(':agentId')) {\n    networkRoute({ path: `${path}/:agentId`, mastra });\n  } else throw e;\n}","preventionTips":["Add a startup-time assertion/test for every registered network route","Adopt a convention: dynamic routes always include :agentId","Review route path changes in code review for parameter loss"],"tags":["routing","configuration","http","startup"],"backgroundTag":"missing-route-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}