What causes "Agent ID is required" in mastra-ai/mastra?

Ensure the client sends a non-empty agentId in the URL path, e.g. /agents/my-agent/generate

mastra-ai/mastra · error · HTTPException

Agent ID is required

Error message

Agent ID is required

What it means

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.

Source

Thrown at packages/server/src/server/handlers/agents.ts:918

  }
  return undefined;
}

export async function getAgentFromSystem({
  mastra,
  agentId,
  versionOptions,
  requestContext,
}: {
  mastra: Context['mastra'];
  agentId: string;
  versionOptions?: { status?: 'draft' | 'published' } | { versionId: string };
  requestContext?: RequestContext;
}): Promise<Agent> {
  const logger = mastra.getLogger();

  if (!agentId) {
    throw new HTTPException(400, { message: 'Agent ID is required' });
  }

  let agent: Agent | null | undefined;

  try {
    agent = mastra.getAgentById(agentId);
  } catch (error) {
    logger.debug('Error getting agent from mastra, searching agents for agent', error);
  }

  if (!agent) {
    logger.debug('Agent not found, looking through sub-agents', { agentId });
    const agents = mastra.listAgents();
    if (Object.keys(agents || {}).length) {
      for (const [_, ag] of Object.entries(agents)) {
        try {
          const subAgents = await ag.listAgents();

View on GitHub (pinned to 75dd419e61)

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

Example fix

// before
const url = `/agents/${agentId}/generate`; // agentId is undefined -> /agents//generate
// after
if (!agentId) throw new Error('agentId is required');
const url = `/agents/${agentId}/generate`;

Defensive patterns

Strategy: validation

Validate before calling

function requireAgentId(agentId: string | undefined): string {
  if (typeof agentId !== 'string' || agentId.length === 0) {
    throw new Error('agentId is required');
  }
  return agentId;
}

Type guard

function hasAgentId(params: { agentId?: string }): params is { agentId: string } {
  return typeof params.agentId === 'string' && params.agentId.length > 0;
}

Try / catch

try {
  await client.getAgent(agentId).generate({ messages });
} catch (e) {
  if (isHttpException(e, 400) && String(e.message).includes('Agent ID is required')) {
    // fix URL construction: agentId variable was empty
  }
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/4e6dd195dee961e5. Report an issue: GitHub.