mastra-ai/mastra · critical · HTTPException

Agents storage domain is not available

Error message

Agents storage domain is not available

What it means

After storage resolves, getFavoritesContext requests the 'agents' storage domain via storage.getStore('agents'). A null/undefined store means the configured storage adapter doesn't provide the agents domain, so the handler throws HTTPException 500. This catches storage adapters that lack agent persistence support.

Source

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

import { storedAgentIdPathParams } from '../schemas/stored-agents';
import { createRoute } from '../server-adapter/routes/route-builder';
import { assertStoredResourceScope, getStoredResourceScope } from '../utils';

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

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade or switch to a storage adapter that implements the agents domain
2. Run the adapter's schema migration/init so agent tables exist
3. Check the adapter version compatibility with the installed @mastra/core
4. Verify storage.getStore('agents') directly in a startup health check

Example fix

// before
storage: new MinimalStorage() // no agents domain
// after
storage: new MastraLibSQLStorage({ url: DATABASE_URL }) // full domain support

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

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

try {
  await favoritesApi.add(agentId);
} catch (e) {
  if (e.status === 500 && /Agents storage domain/.test(e.message)) {
    reportStorageAdapterIncompatibility();
  } else throw e;
}

When it happens

Trigger: Hitting a stored-agent favorites endpoint with a storage backend configured but whose getStore('agents') returns null — i.e. an adapter that doesn't implement the agents domain.

Common situations: Using a minimal/custom storage adapter missing the agents store; storage adapter version too old to include the agents domain; misconfigured adapter initialized without agent tables/collections.

Related errors

• Prompt blocks storage domain is not available
• Favorites storage domain is not available
• Skills storage domain is not available
• AcpAgent does not support resuming suspended generate calls
• AcpAgent does not support resuming suspended stream calls

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