mastra-ai/mastra · error · HTTPException

Stored agent with id ${storedAgentId} not found

Error message

Stored agent with id ${storedAgentId} not found

What it means

GET /stored/agents/:storedAgentId returns 404 when getByIdResolved finds no agent for the id at the requested status (published default, or draft with ?status=draft). Because of visibility scoping, a private agent you can't read also surfaces as 404 rather than 403, so this error can mean 'doesn't exist' or 'exists but not visible to you'.

Source

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

  tags: ['Stored Agents'],
  requiresAuth: true,
  handler: async ({ mastra, requestContext, storedAgentId, status }) => {
    try {
      const storage = mastra.getStorage();

      if (!storage) {
        throw new HTTPException(500, { message: 'Storage is not configured' });
      }

      const agentsStore = await storage.getStore('agents');
      if (!agentsStore) {
        throw new HTTPException(500, { message: 'Agents storage domain is not available' });
      }

      const agent = await agentsStore.getByIdResolved(storedAgentId, { status });

      if (!agent) {
        throw new HTTPException(404, { message: `Stored agent with id ${storedAgentId} not found` });
      }
      assertStoredResourceScope(agent, await getStoredResourceScope(mastra, requestContext));

      // Throws 404 if the caller isn't the owner, admin, `stored-agents:read[:<id>]`
      // holder, and the record isn't public/legacy-unowned.
      assertReadAccess({ requestContext, resource: 'stored-agents', resourceId: storedAgentId, record: agent });

      const authors = await prepareAuthorEnrichment(mastra, requestContext, [agent.authorId]);
      const withFavorite = await enrichOrStripFavorites(mastra, requestContext, 'agent', agent);
      return attachAuthor(withFavorite, authors);
    } catch (error) {
      return handleError(error, 'Error getting stored agent');
    }
  },
});

/**
 * POST /stored/agents - Create a new stored agent

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Retry with ?status=draft to check whether only a draft version exists
  2. List GET /stored/agents to confirm the id is visible to your credentials
  3. Verify permissions: owner/admin or stored-agents:read[:<id>] plus a public/legacy-unowned record is required for non-owner reads
  4. Confirm you're querying the environment whose storage actually holds the agent

Example fix

// before
get(`/stored/agents/${id}`); // 404, only draft exists
// after
get(`/stored/agents/${id}?status=draft`);
Defensive patterns

Strategy: try-catch

Validate before calling

const list = await get('/stored/agents');
const visible = list.agents.some(a => a.id === id);
if (!visible) throw new Error(`Agent ${id} not visible/absent for current credentials`);

Type guard

function isAgentNotFound(e: unknown): boolean {
  return (e as any)?.status === 404 && /Stored agent with id .* not found/.test((e as any)?.message ?? '');
}

Try / catch

try {
  return await get(`/stored/agents/${id}`);
} catch (e) {
  if (isAgentNotFound(e)) {
    // retry as draft before giving up
    return get(`/stored/agents/${id}?status=draft`).catch(() => null);
  }
  throw e;
}

Prevention

When it happens

Trigger: GET /stored/agents/:id with an unknown id; id exists only as a draft while requesting published (default); agent deleted; requesting another user's private agent without admin rights or stored-agents:read permission (assertReadAccess/scoping converts it to 404).

Common situations: Playground UI stale link after agent deletion; querying ?status=published for an agent never published; cross-tenant id in multi-tenant deployment; wrong environment (agent exists in prod, queried in staging).

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/eba175883a772c95. Report an issue: GitHub.