mastra-ai/mastra · critical · HTTPException

Agents storage domain is not available

Error message

Agents storage domain is not available

What it means

After storage is configured, the handler calls storage.getStore('agents') to get the agents domain store; a storage adapter that doesn't implement/support the 'agents' domain returns undefined, producing HTTP 500. This distinguishes 'storage missing entirely' from 'storage present but the agents domain is unavailable'.

Source

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

    perPage,
    orderBy,
    status,
    authorId,
    visibility,
    metadata,
    favoritedOnly,
    pinFavoritedFor,
  }) => {
    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' });
      }

      // Resolve the visibility scope for this caller. Non-owner queries for
      // another author return only that author's public rows; default lists
      // return the caller's rows plus legacy unowned records.
      const filter = resolveAuthorFilter({
        requestContext,
        resource: 'stored-agents',
        queryAuthorId: authorId,
        queryVisibility: visibility === 'public' ? 'public' : undefined,
      });

      const scope = await getStoredResourceScope(mastra, requestContext);
      const scopedMetadata = scopeStoredResourceMetadata(metadata, scope);

      const callerId = getCallerAuthorId(requestContext);
      const favoritesEnabled = await isBuilderFeatureEnabled(mastra, 'favorites');
      const honoredStarredOnly = favoritesEnabled && favoritedOnly === true;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use an official storage adapter (@mastra/pg, @mastra/libsql, @mastra/upstash) that supports the agents domain
2. Update the storage adapter package to a version compatible with your @mastra/core version
3. Check adapter logs for failed initialization of domain stores
4. If using a custom adapter, implement getStore('agents') returning a functional agents store

Example fix

// before
storage: new MyMinimalStore() // getStore('agents') -> undefined
// after
storage: new PostgresStore({ connectionString: process.env.DATABASE_URL })

const store = await mastra.getStorage()?.getStore('agents');
if (!store) throw new Error('Storage adapter lacks agents domain; use an official adapter');

function hasAgentsStore(s: { getStore(d: string): Promise<unknown> }): Promise<boolean> {
  return s.getStore('agents').then(Boolean);
}

try {
  return await get('/stored/agents');
} catch (e) {
  if ((e as any).status === 500 && /Agents storage domain/.test((e as any).message)) {
    throw new Error('Replace/upgrade the storage adapter to one supporting the agents domain');
  }
  throw e;
}

When it happens

Trigger: GET /stored/agents against a custom or partial storage adapter that doesn't provide the agents store; storage adapter connected but domain stores not initialized; using a legacy adapter version lacking the agents domain.

Common situations: Custom MastraStorage implementation that returns null from getStore for 'agents'; version mismatch where @mastra/core storage interface changed and a third-party adapter no longer registers the agents domain; adapter initialized lazily and initialization failed silently.

Related errors

• AcpAgent does not support resuming suspended generate calls
• AcpAgent does not support resuming suspended stream calls
• ACP prompt stopped before completing: ${response.stopReason}
• ClaudeSDKAgent resumeData must include a message.
• Storage is not configured

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