{"record":{"id":"ac830e3a082944bb","repo":"mastra-ai/mastra","slug":"agent-id-is-required","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/chat-route.ts","lineNumber":704,"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":686,"sourceCodeEnd":722,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/chat-route.ts#L686-L722","documentation":"Inside the route handler, after merging all possible agent sources (URL :agentId param, explicit agent option, request context), agentToUse is still undefined. Without an agent the handler cannot proceed, so it throws per-request (as opposed to error 147, which throws at registration).","triggerScenarios":"POSTing to the chat route with a URL that lacks the :agentId segment (e.g. missing path parameter at request time) while no explicit agent option was provided; calling the generated route path incorrectly from the client.","commonSituations":"Client hitting '/api/chat/' instead of '/api/chat/my-agent'; framework routing that strips empty path params; registration used ':agentId' but the fetch URL forgot to interpolate the agent ID (literal ':agentId' sent as text or empty string).","solutions":["Ensure the request URL includes the actual agent ID: fetch(`/api/chat/${agentId}`)","Pass the agent explicitly at registration to remove dependence on the URL","Check for a client-side variable that is empty/undefined when building the URL","If registration should have thrown but didn't (agent passed via context), verify the request context actually carries the agent"],"exampleFix":"// before\nfetch(`/api/chat/${undefined}`)\n// after\nif (!agentId) throw new Error('agentId required');\nfetch(`/api/chat/${agentId}`)","handlingStrategy":"validation","validationCode":"const url = new URL(req.url);\nconst agentId = url.pathname.split('/').pop();\nif (!agentId) throw new Error('Request URL must include the agentId path segment');","typeGuard":"function hasAgentId(pathname: string): boolean {\n  const seg = pathname.split('/').filter(Boolean).pop();\n  return typeof seg === 'string' && seg.length > 0 && seg !== ':agentId';\n}","tryCatchPattern":"try {\n  const res = await fetch(chatUrl, init);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Agent ID is required')) {\n    console.error(`chatUrl \"${chatUrl}\" is missing the agentId segment`);\n  }\n  throw err;\n}","preventionTips":["Build the chat URL with an interpolated agent ID and assert it is non-empty first","Never send the literal string ':agentId' — interpolate the real ID","Pass the agent explicitly at registration if the URL structure is out of your control","Add a client-side check that agentId is defined before invoking fetch"],"tags":["ai-sdk","routing","request-validation"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}