mastra-ai/mastra · error · HTTPException

Stored agent with id

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'.

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`);

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`);

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

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;
}

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

• Agent with id not found
• Not found
• Not found
• Stored agent with id
• Access denied: cannot save messages for a different resource

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

Appendix: 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)