mastra-ai/mastra · error

Agent ID is required

Error message

Agent ID is required

What it means

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).

Source

Thrown at client-sdks/ai-sdk/src/chat-route.ts:704

            `Fixed agent ID was set together with an agentId path parameter. This can lead to unexpected behavior.`,
          );
      }

      // Prioritize requestContext from middleware/route options over body
      const effectiveRequestContext = contextRequestContext || defaultOptions?.requestContext || params.requestContext;

      if (
        (contextRequestContext && defaultOptions?.requestContext) ||
        (contextRequestContext && params.requestContext) ||
        (defaultOptions?.requestContext && params.requestContext)
      ) {
        mastra
          .getLogger()
          ?.warn(`Multiple "requestContext" sources provided. Using priority: middleware > route options > body.`);
      }

      if (!agentToUse) {
        throw new Error('Agent ID is required');
      }

      // Resolve agent version from query params, falling back to static option
      const queryVersionId = c.req.query('versionId');
      const rawStatus = c.req.query('status');

      if (queryVersionId && rawStatus) {
        throw new Error('Query parameters "versionId" and "status" are mutually exclusive');
      }

      if (rawStatus && rawStatus !== 'draft' && rawStatus !== 'published') {
        throw new Error('Query parameter "status" must be "draft" or "published"');
      }

      const queryStatus = rawStatus as 'draft' | 'published' | undefined;
      const effectiveAgentVersion: AgentVersionOptions | undefined = queryVersionId
        ? { versionId: queryVersionId }
        : queryStatus

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure the request URL includes the actual agent ID: fetch(`/api/chat/${agentId}`)
2. Pass the agent explicitly at registration to remove dependence on the URL
3. Check for a client-side variable that is empty/undefined when building the URL
4. If registration should have thrown but didn't (agent passed via context), verify the request context actually carries the agent

Example fix

// before
fetch(`/api/chat/${undefined}`)
// after
if (!agentId) throw new Error('agentId required');
fetch(`/api/chat/${agentId}`)

const url = new URL(req.url);
const agentId = url.pathname.split('/').pop();
if (!agentId) throw new Error('Request URL must include the agentId path segment');

function hasAgentId(pathname: string): boolean {
  const seg = pathname.split('/').filter(Boolean).pop();
  return typeof seg === 'string' && seg.length > 0 && seg !== ':agentId';
}

try {
  const res = await fetch(chatUrl, init);
} catch (err) {
  if (err instanceof Error && err.message.includes('Agent ID is required')) {
    console.error(`chatUrl "${chatUrl}" is missing the agentId segment`);
  }
  throw err;
}

When it happens

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

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

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

• Agent ${agentId} not found
• Path must include :agentId to route to the correct agent or
• runId is required when resumeData is provided
• Messages must be an array of UIMessage objects
• Query parameters "versionId" and "status" are mutually exclu

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