mastra-ai/mastra · error · HTTPException

Storage is not configured

Error message

Storage is not configured

What it means

The GET /stored/workspaces list handler requires a configured storage instance because workspaces are persisted. mastra.getStorage() returned undefined, so the handler throws a 500 before touching the workspace store. Mastra cannot list stored workspaces without a database backend.

Source

Thrown at packages/server/src/server/handlers/stored-workspaces.ts:47

/**
 * GET /stored/workspaces - List all stored workspaces
 */
export const LIST_STORED_WORKSPACES_ROUTE = createRoute({
  method: 'GET',
  path: '/stored/workspaces',
  responseType: 'json',
  queryParamSchema: listStoredWorkspacesQuerySchema,
  responseSchema: listStoredWorkspacesResponseSchema,
  summary: 'List stored workspaces',
  description: 'Returns a paginated list of all workspace configurations stored in the database',
  tags: ['Stored Workspaces'],
  requiresAuth: true,
  handler: async ({ mastra, page, perPage, orderBy, authorId, metadata, requestContext }) => {
    try {
      const storage = mastra.getStorage();

      if (!storage) {
        throw new HTTPException(500, { message: 'Storage is not configured' });
      }

      const workspaceStore = await storage.getStore('workspaces');
      if (!workspaceStore) {
        throw new HTTPException(500, { message: 'Workspaces storage domain is not available' });
      }

      // Resolve the visibility scope for this caller. Non-owner queries for
      // another author return nothing (workspaces have no `public` visibility
      // yet); default lists return the caller's rows plus legacy unowned
      // records.
      const filter = resolveAuthorFilter({
        requestContext,
        resource: 'stored-workspaces',
        queryAuthorId: authorId,
      });

      const scope = await getStoredResourceScope(mastra, requestContext);

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Configure storage when constructing Mastra, e.g. new Mastra({ storage: new MastraStorage({ ... }) }) with a concrete adapter like LibSQLStore or PgStore
  2. Set the storage connection env vars (database URL etc.) your adapter requires
  3. If storage should be optional, guard the client: check the error and skip stored-workspace features when unconfigured
  4. Restart the server after adding storage config to the Mastra constructor

Example fix

// before
export const mastra = new Mastra({ agents: { weather } });
// after
import { Mastra } from '@mastra/core';
import { LibSQLStore } from '@mastra/libsql';
export const mastra = new Mastra({
  agents: { weather },
  storage: new LibSQLStore({ url: process.env.DATABASE_URL! }),
});
Defensive patterns

Strategy: validation

Validate before calling

import { Mastra } from '@mastra/core';
export function assertStorage(mastra: Mastra) {
  if (!mastra.getStorage()) {
    throw new Error('Configure storage: new Mastra({ storage: new LibSQLStore({ url: process.env.DATABASE_URL! }) })');
  }
}

Try / catch

try {
  const res = await fetch(`${baseUrl}/api/stored/workspaces`);
  if (!res.ok) throw Object.assign(new Error(await res.text()), { status: res.status });
} catch (e: any) {
  if (e.status === 500 && String(e.message).includes('Storage is not configured')) {
    console.error('Add a storage adapter to your Mastra instance');
  } else throw e;
}

Prevention

When it happens

Trigger: GET /api/stored/workspaces on a Mastra instance constructed without a storage option (no LibSQL/PG/Upstash storage configured).

Common situations: Local dev/prototype Mastra instance created without storage; storage removed during refactor; deploying the playground/server against an in-memory Mastra that never had persistence wired.

Related errors

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