{"record":{"id":"4e6dd195dee961e5","repo":"mastra-ai/mastra","slug":"agent-id-is-required-4e6dd1","errorCode":null,"errorMessage":"Agent ID is required","messagePattern":"Agent ID is required","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/agents.ts","lineNumber":918,"sourceCode":"  }\n  return undefined;\n}\n\nexport async function getAgentFromSystem({\n  mastra,\n  agentId,\n  versionOptions,\n  requestContext,\n}: {\n  mastra: Context['mastra'];\n  agentId: string;\n  versionOptions?: { status?: 'draft' | 'published' } | { versionId: string };\n  requestContext?: RequestContext;\n}): Promise<Agent> {\n  const logger = mastra.getLogger();\n\n  if (!agentId) {\n    throw new HTTPException(400, { message: 'Agent ID is required' });\n  }\n\n  let agent: Agent | null | undefined;\n\n  try {\n    agent = mastra.getAgentById(agentId);\n  } catch (error) {\n    logger.debug('Error getting agent from mastra, searching agents for agent', error);\n  }\n\n  if (!agent) {\n    logger.debug('Agent not found, looking through sub-agents', { agentId });\n    const agents = mastra.listAgents();\n    if (Object.keys(agents || {}).length) {\n      for (const [_, ag] of Object.entries(agents)) {\n        try {\n          const subAgents = await ag.listAgents();\n","sourceCodeStart":900,"sourceCodeEnd":936,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/agents.ts#L900-L936","documentation":"Thrown by getAgentFromSystem (the shared helper that resolves an Agent instance for agent routes) when the agentId argument is falsy. This is a request-validation 400 that fires before any lookup against the Mastra registry or storage.","triggerScenarios":"Calling any agent route (generate, stream, etc.) with an empty or missing :agentId path parameter, or programmatically invoking getAgentFromSystem with agentId: undefined/null, e.g. from a destructured request where the param name mismatched.","commonSituations":"Client code building URLs with an undefined agent id (template string with an unset variable); route registration/proxy strips the path param; calling the helper directly in custom handlers without validating inputs.","solutions":["Ensure the client sends a non-empty agentId in the URL path, e.g. /agents/my-agent/generate","Check that the variable interpolated into the URL is actually defined before making the request","Validate agentId at the call site (early return / 400) when invoking getAgentFromSystem directly"],"exampleFix":"// before\nconst url = `/agents/${agentId}/generate`; // agentId is undefined -> /agents//generate\n// after\nif (!agentId) throw new Error('agentId is required');\nconst url = `/agents/${agentId}/generate`;","handlingStrategy":"validation","validationCode":"function requireAgentId(agentId: string | undefined): string {\n  if (typeof agentId !== 'string' || agentId.length === 0) {\n    throw new Error('agentId is required');\n  }\n  return agentId;\n}","typeGuard":"function hasAgentId(params: { agentId?: string }): params is { agentId: string } {\n  return typeof params.agentId === 'string' && params.agentId.length > 0;\n}","tryCatchPattern":"try {\n  await client.getAgent(agentId).generate({ messages });\n} catch (e) {\n  if (isHttpException(e, 400) && String(e.message).includes('Agent ID is required')) {\n    // fix URL construction: agentId variable was empty\n  }\n}","preventionTips":["Validate path parameters at the client call site before building URLs","Use typed route builders that reject empty path segments","Log the full request URL on 400s to catch undefined-interpolation bugs early"],"tags":["http-400","validation","rest-api","agents"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}