mastra-ai/mastra · error · HTTPException

Agent with id ${storedAgentId} not found

Error message

Agent with id ${storedAgentId} not found

What it means

buildStoredAgentExport (used by POST /stored/agents/:storedAgentId/export and the change-request route) looks up the agent both in the agents store and via mastra.getAgentById (code-defined agents). If neither yields a result, it throws HTTP 404 — export needs either a stored override or a code-defined agent to serialize.

Source

Thrown at packages/server/src/server/handlers/stored-agents.ts:394

  body: Record<string, unknown>;
}) {
  const storage = mastra.getStorage();
  const agentsStore = storage ? await storage.getStore('agents') : undefined;
  const storedAgent = await agentsStore?.getByIdResolved(storedAgentId, { status: 'draft' });
  if (storedAgent) {
    assertStoredResourceScope(storedAgent, await getStoredResourceScope(mastra, requestContext));
    assertReadAccess({ requestContext, resource: 'stored-agents', resourceId: storedAgentId, record: storedAgent });
  }

  let codeAgent: { __getEditorConfig?: () => unknown; source?: string } | undefined;
  try {
    codeAgent = mastra.getAgentById?.(storedAgentId) as typeof codeAgent;
  } catch {
    codeAgent = undefined;
  }

  if (!storedAgent && !codeAgent) {
    throw new HTTPException(404, { message: `Agent with id ${storedAgentId} not found` });
  }

  const config = buildExportConfig(body, codeAgent);
  const content = `${JSON.stringify(config, null, 2)}\n`;

  return {
    agentId: storedAgentId,
    fileName: agentExportFilename(storedAgentId),
    content,
    config,
  };
}

export const EXPORT_STORED_AGENT_ROUTE = createRoute({
  method: 'POST',
  path: '/stored/agents/:storedAgentId/export',
  responseType: 'json',
  pathParamSchema: storedAgentIdPathParams,

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Confirm the id with GET /stored/agents/:id or by listing agents before exporting
  2. Ensure the code-defined agent is registered in the Mastra instance running on the server
  3. Point the client at the correct environment/deployment that contains the agent
  4. Fix the id typo/casing in the request URL

Example fix

// before
post(`/stored/agents/${'My-Agent'}/export`, body); // wrong casing
// after
post(`/stored/agents/${'my-agent'}/export`, body);
Defensive patterns

Strategy: validation

Validate before calling

const stored = await fetch(`${base}/stored/agents/${id}`).then(r => r.ok);
if (!stored) throw new Error(`Cannot export: agent ${id} not found in storage or code`);

Type guard

function isExportNotFound(e: unknown): e is { status: number; message: string } {
  return typeof e === 'object' && e !== null && (e as any).status === 404 && /not found/.test((e as any).message ?? '');
}

Try / catch

try {
  return await post(`/stored/agents/${id}/export`, body);
} catch (e) {
  if (isExportNotFound(e)) {
    console.error(`Agent ${id} not found in storage or registered code agents`);
    return null;
  }
  throw e;
}

Prevention

When it happens

Trigger: POST /stored/agents/:id/export or POST /stored/agents/:id/change-request with an id that exists in neither storage nor the registered code agents (typo, agent deleted, server running older code without the agent, wrong environment).

Common situations: Exporting from a server whose code was updated and the agent was removed; ID from a different deployment; agent defined only in a branch not running on the server; case-sensitivity mismatch in the agent id.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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