mastra-ai/mastra · critical · HTTPException

Favorites storage domain is not available

Error message

Favorites storage domain is not available

What it means

getFavoritesContext also requires the 'favorites' storage domain, requested via storage.getStore('favorites'). If that store is unavailable on the configured adapter, it throws HTTPException 500. Favorites persistence is a separate domain from agents and must be present even when agents storage works.

Source

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

import { assertReadAccess, getCallerAuthorId } from './authorship';
import { requireBuilderFeature } from './editor-builder';
import { handleError } from './error';

/**
 * Resolves the storage and favorites domains, throwing 500 if unavailable.
 */
async function getFavoritesContext(mastra: Parameters<typeof requireBuilderFeature>[0]) {
  const storage = mastra.getStorage();
  if (!storage) {
    throw new HTTPException(500, { message: 'Storage is not configured' });
  }
  const agentStore = await storage.getStore('agents');
  if (!agentStore) {
    throw new HTTPException(500, { message: 'Agents storage domain is not available' });
  }
  const favoritesStore = await storage.getStore('favorites');
  if (!favoritesStore) {
    throw new HTTPException(500, { message: 'Favorites storage domain is not available' });
  }
  return { agentStore, favoritesStore };
}

/**
 * PUT /stored/agents/:storedAgentId/favorite
 */
export const FAVORITE_STORED_AGENT_ROUTE = createRoute({
  method: 'PUT',
  path: '/stored/agents/:storedAgentId/favorite',
  responseType: 'json',
  pathParamSchema: storedAgentIdPathParams,
  responseSchema: favoriteToggleResponseSchema,
  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',

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Upgrade the storage adapter to a version supporting the favorites domain
  2. Run database migrations so favorites tables exist
  3. Add a startup check asserting all required domains (agents, favorites) are available
  4. Disable the favorites builder feature if the storage backend can't support it

Example fix

// before
storage: oldAdapter v1 // lacks favorites store
// after
pnpm up @mastra/libsql@latest && run migrations
Defensive patterns

Strategy: validation

Validate before calling

const storage = mastra.getStorage();
if (storage && !(await storage.getStore('favorites'))) {
  throw new Error('Storage adapter does not provide the favorites domain');
}

Type guard

async function hasFavoritesDomain(storage: MastraStorage): Promise<boolean> {
  return (await storage.getStore('favorites')) != null;
}

Try / catch

try {
  await favoritesApi.list();
} catch (e) {
  if (e.status === 500 && /Favorites storage domain/.test(e.message)) {
    runMigrationsAndAlert();
  } else throw e;
}

Prevention

When it happens

Trigger: Calling a favorites endpoint where storage and the agents store resolve, but storage.getStore('favorites') returns null (adapter lacking the favorites domain).

Common situations: Older storage adapter versions predating the favorites domain; adapters that implement agents but not favorites; schema not migrated after upgrading core/server packages.

Related errors

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