mastra-ai/mastra · critical · HTTPException

Storage is not configured

Error message

Storage is not configured

What it means

LIST_STORED_AGENTS (GET /stored/agents) requires persistent storage; mastra.getStorage() returned undefined, so the server cannot read stored agents at all. The library throws HTTP 500 because listing stored agents is impossible without a configured storage adapter — this is a server deployment/configuration problem, not a client error.

Source

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

  requiresAuth: true,
  handler: async ({
    mastra,
    requestContext,
    page,
    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);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Configure a storage adapter: new Mastra({ storage: new MastraStorage(...) }) (e.g. @mastra/pg, @mastra/libsql)
2. Set the required connection env vars for the chosen storage backend (e.g. DATABASE_URL)
3. Verify mastra.getStorage() in the deployed instance returns the adapter (add a startup check/log)
4. If storage is intentionally absent, do not expose the stored-agents routes

Example fix

// before
export const mastra = new Mastra({ agents: {} });
// after
import { MastraStorage } from '@mastra/core/storage';
import { PostgresStore } from '@mastra/pg';
export const mastra = new Mastra({ agents: {}, storage: new PostgresStore({ connectionString: process.env.DATABASE_URL }) });

import { mastra } from './mastra';
if (!mastra.getStorage()) throw new Error('Configure storage before using stored-agents routes');

function hasStorage(m: { getStorage(): unknown }): boolean { return Boolean(m.getStorage()); }

try {
  const res = await get('/stored/agents');
  return res;
} catch (e) {
  if ((e as any).status === 500 && /Storage is not configured/.test((e as any).message)) {
    throw new Error('Server deployed without storage; set a storage adapter in the Mastra constructor');
  }
  throw e;
}

When it happens

Trigger: Calling GET /stored/agents (any list query, including favoritedOnly) against a Mastra server instantiated without storage: no storage option passed to the Mastra constructor, or storage removed during a config refactor.

Common situations: Running mastra dev with a minimal config and no storage: new Mastra({...}) missing storage; deploying without setting the database env vars the storage adapter needs; upgrading Mastra where storage moved to a required field; examples/hello-world configs promoted to a real server.

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/cffd5a1b0ce5adef. Report an issue: GitHub.