What causes "Agent ${agentId} not found" in mastra-ai/mastra?

Verify the agent ID matches mastra.getAgent({ name }) / agent registration exactly

Agent ${agentId} not found

Error message

Agent ${agentId} not found

What it means

handleChatStream resolves the agent via mastra.getAgentById(agentId) before streaming. If no agent with that ID is registered on the Mastra instance, the handler throws. With an editor configured, a second lookup path also resolves stored config overrides, but the code-level registration must exist or be resolvable first.

Source

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

  version = 'v5',
  sendStart = true,
  sendFinish = true,
  sendReasoning = false,
  sendSources = false,
  onError,
  messageMetadata,
}: Omit<ChatStreamHandlerOptions<any, OUTPUT>, 'messageMetadata'> & {
  messageMetadata?: any;
}): Promise<ReadableStream<any>> {
  const { messages, resumeData, runId, requestContext, trigger, ...rest } = params;

  if (resumeData && !runId) {
    throw new Error('runId is required when resumeData is provided');
  }

  const baseAgent = mastra.getAgentById(agentId);
  if (!baseAgent) {
    throw new Error(`Agent ${agentId} not found`);
  }

  // When an editor is configured, an agent's runtime config (instructions, tools,
  // model, ...) can live in stored config rather than the code definition. Studio
  // resolves these stored overrides before every run, so this endpoint must do the
  // same or it would execute a stale/empty code-defined agent (issue #18574). An
  // explicit agentVersion (from query params or route options) wins; otherwise we
  // default to the published version, matching the built-in agent handlers.
  let agentObj = baseAgent;
  const editorAgent = mastra.getEditor?.()?.agent;
  if (editorAgent) {
    agentObj = await editorAgent.applyStoredOverrides(
      baseAgent,
      agentVersion ?? { status: 'published' },
      requestContext as RequestContext | undefined,
    );
  } else if (agentVersion) {
    // No editor configured: preserve the prior behavior of surfacing the

View on GitHub (pinned to 75dd419e61)

Solutions

Verify the agent ID matches mastra.getAgent({ name }) / agent registration exactly
Log or list all registered agents (Object.keys of the agents config) and compare with the requested ID
Ensure the agent is registered unconditionally in the environment handling the request
Update frontend constants/config to the renamed agent ID after refactors

Example fix

// before
useChat({ api: '/api/chat/my-agnt' })
// after
useChat({ api: '/api/chat/my-agent' }) // must match the registered agent ID

Defensive patterns

Strategy: validation

Validate before calling

const agents = mastra.getAgents?.() ?? {};
if (!(agentId in agents)) {
  throw new Error(`Unknown agentId "${agentId}". Available: ${Object.keys(agents).join(', ')}`);
}

Type guard

function agentExists(mastra: Mastra, agentId: string): boolean {
  return mastra.getAgentById(agentId) != null;
}

Try / catch

try {
  const stream = await handleChatStream({ mastra, agentId, ...params });
} catch (err) {
  if (err instanceof Error && /Agent .* not found/.test(err.message)) {
    return new Response(JSON.stringify({ error: 'UNKNOWN_AGENT', agentId }), { status: 404 });
  }
  throw err;
}

Prevention

Keep agent IDs in a shared constants module used by both server registration and client calls
List registered agents when a 404-type agent error occurs to surface mismatches
Avoid conditional agent registration that differs between environments
Grep/rename-check agent IDs during refactors

When it happens

Trigger: POSTing to the chat route with an :agentId (or explicit agent option) that does not match any agent registered on the Mastra instance; agent renamed/removed in code while the client still references the old ID.

Common situations: Typos in the agent ID on the frontend; agents registered conditionally so they are absent in some environments; refactoring that renamed agents without updating client code; requesting a versioned agent whose base definition is gone.

Related errors

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