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

chatRoute() can either serve a fixed agent (passed via the agent option) or resolve the agent dynamically from the URL. Dynamic resolution requires the path template to contain the :agentId param. If neither an explicit agent nor the :agentId param exists, the route cannot know which agent to run, so it throws at registration time (fail fast, before serving requests).

Source

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

 * - Request context from the incoming request overrides `defaultOptions.requestContext` if both are present
 */
export function chatRoute<OUTPUT = undefined, UI_MESSAGE extends SupportedUIMessage = SupportedUIMessage>({
  path = '/chat/:agentId',
  agent,
  defaultOptions,
  experimentalTransform,
  version = 'v5',
  agentVersion,
  sendStart = true,
  sendFinish = true,
  sendReasoning = false,
  sendSources = false,
  heartbeatMs,
  onError,
  messageMetadata,
}: chatRouteOptions<OUTPUT, UI_MESSAGE>): 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');
  }
  assertValidHeartbeatMs(heartbeatMs);

  return registerApiRoute(path, {
    method: 'POST',
    openapi: {
      summary: 'Chat with an agent',
      description: 'Send messages to an agent and stream the response in the AI SDK format',
      tags: ['ai-sdk'],
      parameters: [
        {
          name: 'agentId',
          in: 'path',
          required: true,
          description: 'The ID of the agent to chat with',
          schema: {
            type: 'string',
          },

View on GitHub (pinned to 75dd419e61)

Solutions

Pass the agent explicitly: chatRoute({ agent: myAgent, path: '/api/chat' })
Or include the param in the path: chatRoute({ path: '/api/chat/:agentId' })
Ensure the param is spelled exactly ':agentId'
If using another param name, rename it to ':agentId' or supply the agent option

Example fix

// before
chatRoute({ path: '/api/chat' })
// after
chatRoute({ path: '/api/chat/:agentId' })
// or
chatRoute({ path: '/api/chat', agent: myAgent })

Defensive patterns

Strategy: validation

Validate before calling

if (!agent && !path.includes('/:agentId')) {
  throw new Error('chatRoute requires an explicit agent or a path containing :agentId');
}

Type guard

function chatRouteConfigIsValid(cfg: { agent?: unknown; path: string }): boolean {
  return cfg.agent != null || cfg.path.includes('/:agentId');
}

Try / catch

try {
  const route = chatRoute({ path });
} catch (err) {
  if (err instanceof Error && err.message.includes(':agentId')) {
    console.error('Fix chatRoute config: pass agent or use path /:agentId');
  }
}

Prevention

Decide up front: fixed-agent route (pass agent) vs multi-agent route (use :agentId)
Spell the param exactly ':agentId' — case-sensitive
Add a unit test that registers all routes at module load so config errors surface in CI
When simplifying copied route templates, keep the agent option or the param

When it happens

Trigger: Calling chatRoute({ path: '/api/chat' }) without an agent option and without ':agentId' in the path string; renaming the path segment from ':agentId' to something like ':agentSlug' which the library doesn't recognize.

Common situations: Setting up a single-agent endpoint and forgetting the explicit agent option; copy-pasting a multi-agent path template and simplifying it while removing the agent option; typos like ':agentid' (wrong case).

Related errors

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