mastra-ai/mastra · error

Agent ${agentId} not found

Error message

Agent ${agentId} not found

What it means

handleNetworkStream resolves the target agent via mastra.getAgentById before starting the network stream. If no agent with that ID exists (or the requested version does not), it throws 'Agent <id> not found' instead of streaming an error, so the HTTP request fails.

Source

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

  options: NetworkStreamHandlerOptionsV6<UI_MESSAGE, OUTPUT>,
): Promise<V6UIMessageStream<UI_MESSAGE>>;
export function handleNetworkStream<UI_MESSAGE extends V7UIMessage = V7UIMessage, OUTPUT = undefined>(
  options: NetworkStreamHandlerOptionsV7<UI_MESSAGE, OUTPUT>,
): Promise<V7UIMessageStream<UI_MESSAGE>>;
export async function handleNetworkStream<OUTPUT = undefined>({
  mastra,
  agentId,
  agentVersion,
  params,
  defaultOptions,
  version = 'v5',
}: NetworkStreamHandlerOptions<SupportedUIMessage, OUTPUT>): Promise<SupportedUIMessageStream> {
  const { messages, ...rest } = params;

  const agentObj = agentVersion ? await mastra.getAgentById(agentId, agentVersion) : mastra.getAgentById(agentId);

  if (!agentObj) {
    throw new Error(`Agent ${agentId} not found`);
  }

  if (version === 'v7') {
    const result = await agentObj.network<any>(messages as any, {
      ...defaultOptions,
      ...rest,
    });

    const stream = createUIMessageStreamV7<InternalUIMessageV7>({
      originalMessages: messages as InternalUIMessageV7[],
      execute: async ({ writer }) => {
        for await (const part of toAISdkStream(result, { from: 'network', version: 'v7' })) {
          writer.write(part);
        }
      },
    });

    return stream as unknown as SupportedUIMessageStream;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the agentId matches an agent registered on the Mastra instance (mastra.getAgentById in a REPL/log)
2. Check that the requested agentVersion (or versionId/status) exists for that agent
3. Ensure the route is hitting the environment where the agent is registered
4. If the agent should exist, confirm it is added to the Mastra instance's agents config

Example fix

// before
const res = await fetch('/api/network/agen-preview', {...})
// after
const res = await fetch('/api/network/agent-preview', {...})

const agents = mastra.listAgents();
const id = 'agent-preview';
if (!agents.some(a => a.id === id)) {
  throw new Error(`Cannot call network: agent "${id}" is not registered`);
}

function agentExists(mastra: Mastra, id: string): boolean {
  return Object.values(mastra.getAgents?.() ?? {}).some((a: any) => a.id === id || a.name === id);
}

try {
  const res = await fetch('/api/network/agent-preview', { method: 'POST', body });
  if (!res.ok) throw new Error(await res.text());
} catch (e) {
  if (String(e.message).includes('not found')) {
    console.error(`Agent not registered in this environment: ${e.message}`);
  }
}

When it happens

Trigger: POSTing to the network route with a body/param agentId that does not match any registered agent, or specifying an agentVersion that doesn't exist for that agent.

Common situations: Typos in agent IDs, agents removed or renamed in mastra config while clients still reference old IDs, per-environment registries differing (agent exists locally but not in prod), or draft/published version mismatch when using version options.

Related errors

• Path must include :agentId to route to the correct agent or
• Agent ID is required
• @mastra/livekit: no Mastra agent specified. Set `agent` on c
• Agent ${agentId} not found
• 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/9140e1e91094238e. Report an issue: GitHub.