mastra-ai/mastra · error

Path must include :agentId to route to the correct agent or

Error message

Path must include :agentId to route to the correct agent or pass the agent explicitly

What it means

networkRoute can either bind to a fixed agent passed via options, or dynamically select the agent from the URL. If neither is possible — no explicit agent option and the path lacks the :agentId parameter — the route would have no way to know which agent to run, so it throws at registration time.

Source

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

 * @example
 * // Fixed agent with custom path
 * networkRoute({
 *   path: '/api/orchestrator',
 *   agent: 'router-agent',
 *   defaultOptions: {
 *     maxSteps: 10,
 *   },
 * });
 */
export function networkRoute<OUTPUT = undefined>({
  path = '/network/:agentId',
  agent,
  defaultOptions,
  version = 'v5',
  agentVersion,
}: NetworkRouteOptions<OUTPUT>): ReturnType<typeof registerApiRoute> {
  if (!agent && !path.includes('/:agentId')) {
    throw new Error('Path must include :agentId to route to the correct agent or pass the agent explicitly');
  }

  return registerApiRoute(path, {
    method: 'POST',
    openapi: {
      summary: 'Execute an agent network and stream AI SDK events',
      description: 'Routes a request to an agent network and streams UIMessage chunks in AI SDK format',
      tags: ['ai-sdk'],
      parameters: [
        {
          name: 'agentId',
          in: 'path',
          required: true,
          description: 'The ID of the routing agent to execute as a network',
          schema: { type: 'string' },
        },
        {
          name: 'versionId',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add :agentId to the path, e.g. '/api/network/:agentId'
2. Or pass the agent explicitly: networkRoute({ path: '/api/network', agent: myAgent })
3. Re-check route registration code after refactors of server routes

Example fix

// before
networkRoute({ path: '/api/network', mastra })
// after
networkRoute({ path: '/api/network/:agentId', mastra })
// or
networkRoute({ path: '/api/network', agent: myAgent, mastra })

function assertNetworkRouteOptions(path: string, opts: { agent?: unknown }) {
  if (!opts.agent && !path.includes('/:agentId')) {
    throw new Error('networkRoute requires an explicit agent or a path containing :agentId');
  }
}
assertNetworkRouteOptions('/api/network', {});

null

try {
  networkRoute({ path, mastra });
} catch (e) {
  if (String(e.message).includes(':agentId')) {
    networkRoute({ path: `${path}/:agentId`, mastra });
  } else throw e;
}

When it happens

Trigger: Calling networkRoute({ path: '/api/network' }) without an `agent` option and without '/:agentId' in the path.

Common situations: Copy-pasting route setup that previously included /:agentId and simplifying the path; forgetting to pass the agent when hardcoding a route; upgrading Mastra where this validation became stricter.

Related errors

• Agent ${agentId} not found
• Google client ID is required. Provide it in the options or s
• Agent ${agentId} not found
• Path must include :agentId to route to the correct agent or
• Agent ID is required

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