mastra-ai/mastra · error · HTTPException

Stored agent with id ${storedAgentId} not found

Error message

Stored agent with id ${storedAgentId} not found

What it means

After authentication, the favorites handler loads the stored agent via agentStore.getById(storedAgentId). If no record matches that id, it throws HTTPException 404 with the offending id in the message. Subsequent scope and read-access checks only run when the agent exists.

Source

Thrown at packages/server/src/server/handlers/stored-agent-favorites.ts:57

  summary: 'Favorite a stored agent',
  description: 'Marks the stored agent as favorited by the calling user. Idempotent.',
  tags: ['Stored Agents'],
  requiresAuth: true,
  requiresPermission: 'stored-agents:read',
  handler: async ({ mastra, requestContext, storedAgentId }) => {
    try {
      await requireBuilderFeature(mastra, 'favorites');

      const callerId = getCallerAuthorId(requestContext);
      if (!callerId) {
        throw new HTTPException(401, { message: 'Authentication required' });
      }

      const { agentStore, favoritesStore } = await getFavoritesContext(mastra);

      const agent = await agentStore.getById(storedAgentId);
      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 cannot read the agent (private + not owner/admin).
      assertReadAccess({ requestContext, resource: 'stored-agents', resourceId: storedAgentId, record: agent });

      const result = await favoritesStore.favorite({
        userId: callerId,
        entityType: 'agent',
        entityId: storedAgentId,
      });
      return result;
    } catch (error) {
      return handleError(error, 'Error favoriting stored agent');
    }
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

1. Confirm the storedAgentId exists via the stored agents list endpoint
2. Refresh the UI/client cache and retry with the current id
3. Check that the server's storage points at the environment where the agent lives
4. Handle 404 in the client by removing the stale agent from local state

Example fix

// before
await api.put(`/stored-agents/${staleId}/favorite`);
// after
const agent = await api.get(`/stored-agents/${id}`);
if (agent) await api.put(`/stored-agents/${id}/favorite`);
else removeStaleAgent(id);

const agent = await api.getStoredAgent(storedAgentId).catch(() => null);
if (!agent) throw new Error(`Stored agent ${storedAgentId} does not exist`);

function isStoredAgent(x: unknown): x is { id: string } {
  return typeof x === 'object' && x !== null && typeof (x as any).id === 'string';
}

try {
  await api.toggleFavorite(storedAgentId);
} catch (e) {
  if (e.status === 404) { purgeLocalAgent(storedAgentId); }
  else throw e;
}

When it happens

Trigger: Toggling favorites for a storedAgentId that was deleted, never existed, or belongs to a different storage backend than the one queried.

Common situations: Stale id cached in the UI after the agent was deleted; hard-coded/copy-pasted id from another environment; id typo; storage pointing at a different database than where the agent was created.

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

• Version with id ${versionId} not found
• Prompt block with id ${promptBlockId} not found
• Stored scorer definition with id ${storedScorerId} not found
• Stored skill with id ${storedSkillId} not found
• Model "${modelId}" is not available. Available models: ${ids

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