mastra-ai/mastra · error

Agent ID is required

Error message

Agent ID is required

What it means

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.

Source

Thrown at client-sdks/ai-sdk/src/network-route.ts:333

            `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. Include agentId in the request body, e.g. { agentId: 'myAgent', messages: [...] }
2. Use the /:agentId path form when calling the route
3. Register the route with a default `agent` option so the ID isn't required per-request
4. Validate the client payload against the route's expected shape

Example fix

// before
fetch('/api/network', { body: JSON.stringify({ messages }) })
// after
fetch('/api/network', { body: JSON.stringify({ agentId: 'my-agent', messages }) })

if (!body.agentId || typeof body.agentId !== 'string') {
  throw new Error('Request body must include a string agentId');
}

function hasAgentId(b: unknown): b is { agentId: string } {
  return !!b && typeof b === 'object' && typeof (b as any).agentId === 'string' && (b as any).agentId.length > 0;
}

try {
  const res = await fetch('/api/network', { method: 'POST', body: JSON.stringify(payload) });
  if (!res.ok) throw new Error(await res.text());
} catch (e) {
  if (String(e.message).includes('Agent ID is required')) {
    console.error('Add agentId to the request body or use the /:agentId path');
  }
}

When it happens

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

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

Related errors

• Agent ${agentId} not found
• Agent "${agentId}" not found
• No agent or agent controller found with id "${agentId}"
• Query parameter "status" must be "draft" or "published"
• Path must include :agentId to route to the correct agent or

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