mastra-ai/mastra · error · HTTPException

Agents storage domain is not available

Error message

Agents storage domain is not available

What it means

This 500 is thrown by the LIST_AGENT_VERSIONS route (GET /stored/agents/:agentId/versions) when Mastra storage is configured, but storage.getStore('agents') returns no agents domain store. It means the configured storage adapter does not implement (or failed to initialize) the 'agents' store domain, so agent versions cannot be listed.

Source

Thrown at packages/server/src/server/handlers/agent-versions.ts:83

  requiresAuth: true,
  responseType: 'json',
  pathParamSchema: agentVersionPathParams,
  queryParamSchema: listVersionsQuerySchema,
  responseSchema: listVersionsResponseSchema,
  summary: 'List agent versions',
  description: 'Returns a paginated list of all versions for a stored agent',
  tags: ['Agent Versions'],
  handler: async ({ mastra, agentId, page, perPage, orderBy, requestContext }) => {
    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' });
      }

      // Verify agent exists in code or storage
      const storedAgent = await agentsStore.getById(agentId);
      let codeAgentExists = false;
      try {
        mastra.getAgentById(agentId);
        codeAgentExists = true;
      } catch {
        // Agent not registered in code
      }

      if (!storedAgent && !codeAgentExists) {
        throw new HTTPException(404, { message: `Agent with id ${agentId} not found` });
      }
      assertStoredResourceScope(storedAgent, await getStoredResourceScope(mastra, requestContext));

      const result = await agentsStore.listVersions({

View on GitHub (pinned to 75dd419e61)

Solutions

1. Configure a full storage adapter (e.g. @mastra/libsql, @mastra/pg, @mastra/upstash) that implements the agents domain
2. Verify the storage adapter version supports agent versioning (getStore('agents')) and upgrade it if not
3. Check storage initialization logs/errors for why the agents domain store failed to load
4. If agents storage is intentionally absent, stop calling the /stored/agents/:agentId/versions endpoints

Example fix

// before
new Mastra({ storage: new PartialStorageAdapter({ traces: true }) });
// after
import { LibSQLStore } from '@mastra/libsql';
new Mastra({ storage: new LibSQLStore({ url: 'file:./mastra.db' }) });

const storage = mastra.getStorage();
if (!storage) throw new Error('Mastra storage is not configured');
const agentsStore = await storage.getStore('agents');
if (!agentsStore) throw new Error('Storage adapter lacks an agents domain; use a full adapter like LibSQLStore/PgStore');

function hasAgentsStore(s: unknown): s is { getStore: (d: 'agents') => Promise<unknown> } {
  return !!s && typeof (s as any).getStore === 'function';
}

try {
  const res = await fetch(`/api/stored/agents/${agentId}/versions`);
  if (res.status === 500) {
    const body = await res.json();
    if (String(body.message).includes('storage')) throw new Error('Server storage misconfigured — configure a full storage adapter');
  }
} catch (e) { /* surface config error to operator */ }

When it happens

Trigger: Calling the list-agent-versions API against a Mastra instance whose storage adapter lacks an agents domain, or whose getStore('agents') initialization returns null/undefined at request time.

Common situations: Using a custom or legacy storage adapter that only implements some domains (e.g. traces or workflows) but not agents; storage configured without agent-versioning support; a partially-failed storage initialization after a dependency or adapter upgrade.

Related errors

• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• Experiments storage not available
• Storage is not configured
• Storage is not configured

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