{"record":{"id":"d2c7e34831170dbe","repo":"mastra-ai/mastra","slug":"agent-id-is-required-d2c7e3","errorCode":null,"errorMessage":"Agent ID is required","messagePattern":"Agent ID is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/ai-sdk/src/network-route.ts","lineNumber":333,"sourceCode":"            `Fixed agent ID was set together with an agentId path parameter. This can lead to unexpected behavior.`,\n          );\n      }\n\n      // Prioritize requestContext from middleware/route options over body\n      const effectiveRequestContext = contextRequestContext || defaultOptions?.requestContext || params.requestContext;\n\n      if (\n        (contextRequestContext && defaultOptions?.requestContext) ||\n        (contextRequestContext && params.requestContext) ||\n        (defaultOptions?.requestContext && params.requestContext)\n      ) {\n        mastra\n          .getLogger()\n          ?.warn(`Multiple \"requestContext\" sources provided. Using priority: middleware > route options > body.`);\n      }\n\n      if (!agentToUse) {\n        throw new Error('Agent ID is required');\n      }\n\n      // Resolve agent version from query params, falling back to static option\n      const queryVersionId = c.req.query('versionId');\n      const rawStatus = c.req.query('status');\n\n      if (queryVersionId && rawStatus) {\n        throw new Error('Query parameters \"versionId\" and \"status\" are mutually exclusive');\n      }\n\n      if (rawStatus && rawStatus !== 'draft' && rawStatus !== 'published') {\n        throw new Error('Query parameter \"status\" must be \"draft\" or \"published\"');\n      }\n\n      const queryStatus = rawStatus as 'draft' | 'published' | undefined;\n      const effectiveAgentVersion: AgentVersionOptions | undefined = queryVersionId\n        ? { versionId: queryVersionId }\n        : queryStatus","sourceCodeStart":315,"sourceCodeEnd":351,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/network-route.ts#L315-L351","documentation":"Inside the network route handler, the code resolved which agent to use (from path param, explicit option, or body) and found none. It throws 'Agent ID is required' because a network request cannot proceed without a target agent.","triggerScenarios":"POSTing to a network route registered without a default agent while the request omits both the :agentId path parameter and any agent id in the request body.","commonSituations":"Clients calling a generic network endpoint but forgetting the agentId field in the JSON body; route registered with dynamic path but client hits the base path directly.","solutions":["Include agentId in the request body, e.g. { agentId: 'myAgent', messages: [...] }","Use the /:agentId path form when calling the route","Register the route with a default `agent` option so the ID isn't required per-request","Validate the client payload against the route's expected shape"],"exampleFix":"// before\nfetch('/api/network', { body: JSON.stringify({ messages }) })\n// after\nfetch('/api/network', { body: JSON.stringify({ agentId: 'my-agent', messages }) })","handlingStrategy":"validation","validationCode":"if (!body.agentId || typeof body.agentId !== 'string') {\n  throw new Error('Request body must include a string agentId');\n}","typeGuard":"function hasAgentId(b: unknown): b is { agentId: string } {\n  return !!b && typeof b === 'object' && typeof (b as any).agentId === 'string' && (b as any).agentId.length > 0;\n}","tryCatchPattern":"try {\n  const res = await fetch('/api/network', { method: 'POST', body: JSON.stringify(payload) });\n  if (!res.ok) throw new Error(await res.text());\n} catch (e) {\n  if (String(e.message).includes('Agent ID is required')) {\n    console.error('Add agentId to the request body or use the /:agentId path');\n  }\n}","preventionTips":["Validate request payloads client-side before POSTing","Prefer routes registered with a default agent when only one network is used","Document the required body shape (agentId, messages) for API consumers"],"tags":["http","routing","validation","agents"],"backgroundTag":"missing-required-identifier","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}