What causes "Storage not configured" in mastra-ai/mastra?

Configure storage on the Mastra instance, e.g. new Mastra({ storage: new LibSQLStore({ url: 'file:./mastra.db' }) }).

mastra-ai/mastra · error · HTTPException

Storage not configured

Error message

Storage not configured

What it means

HTTP 500 thrown by the list-experiments handler when mastra.getStorage() returns undefined, meaning the Mastra instance has no storage configured. Experiments are persisted through the storage layer's experiments store, so without storage the endpoint cannot serve results. A sibling 500 ('Experiments storage not available') is thrown if storage exists but lacks an experiments store.

Source

Thrown at packages/server/src/server/handlers/datasets.ts:619

// ============================================================================

export const LIST_ALL_EXPERIMENTS_ROUTE = createRoute({
  method: 'GET',
  path: '/experiments',
  responseType: 'json',
  queryParamSchema: listExperimentsQuerySchema,
  responseSchema: listExperimentsResponseSchema,
  summary: 'List all experiments',
  description: 'Returns a paginated list of all experiments across all datasets',
  tags: ['Experiments'],
  requiresAuth: true,
  handler: async ({ mastra, ...params }) => {
    assertDatasetsAvailable();
    try {
      const { page, perPage, experimentSetId, comparisonId, variantId, trialIndex } = params;
      const storage = mastra.getStorage();
      if (!storage) {
        throw new HTTPException(500, { message: 'Storage not configured' });
      }
      const experimentsStore = await storage.getStore('experiments');
      if (!experimentsStore) {
        throw new HTTPException(500, { message: 'Experiments storage not available' });
      }
      const result = await experimentsStore.listExperiments({
        experimentSetId,
        comparisonId,
        variantId,
        trialIndex,
        pagination: { page: page ?? 0, perPage: perPage ?? 20 },
      });
      return { experiments: result.experiments, pagination: result.pagination };
    } catch (error) {
      if (error instanceof MastraError) {
        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });
      }
      return handleError(error, 'Error listing experiments');

View on GitHub (pinned to 75dd419e61)

Solutions

Configure storage on the Mastra instance, e.g. new Mastra({ storage: new LibSQLStore({ url: 'file:./mastra.db' }) }).
Verify the storage backend supports the experiments store — upgrade @mastra/storage (or the chosen adapter) to a version that includes it.
Check deployment env vars so the storage URL/connection is present where the server runs.
If experiments are intentionally unused, stop calling the experiments endpoints or feature-flag them client-side.

Example fix

// before
export const mastra = new Mastra({ agents: { myAgent } });
// after
import { LibSQLStore } from '@mastra/libsql';
export const mastra = new Mastra({
  agents: { myAgent },
  storage: new LibSQLStore({ url: process.env.MASTRA_STORAGE_URL ?? 'file:./mastra.db' }),
});

Defensive patterns

Strategy: validation

Validate before calling

const storage = mastra.getStorage();
if (!storage) throw new Error('Mastra instance has no storage configured; experiments endpoints unavailable');
const store = await storage.getStore('experiments');
if (!store) throw new Error('Storage backend does not support the experiments store; upgrade the adapter');

Type guard

function hasExperimentsStorage(mastra: { getStorage(): unknown }): boolean {
  return Boolean(mastra.getStorage());
}

Try / catch

try {
  const experiments = await api.listExperiments(datasetId);
} catch (e) {
  if ((e as any)?.status === 500 && /Storage not configured/.test((e as any)?.message ?? '')) {
    console.error('Configure storage on the Mastra instance to use experiments');
    return [];
  }
  throw e;
}

Prevention

Always pass a storage adapter when constructing Mastra if you use experiments/datasets.
Verify env vars for the storage URL exist in every deployment environment.
Use a storage adapter version that implements the experiments store; check getStore('experiments') at startup.
Feature-flag experiments UI when storage is intentionally absent (e.g. ephemeral dev mode).

When it happens

Trigger: GET /api/datasets/:datasetId/experiments (list/compare/review routes) against a Mastra instance constructed without a storage option, e.g. `new Mastra({ ... })` with no `storage:` entry.

Common situations: Running Mastra in dev/in-memory mode and then calling experiments endpoints; forgetting to add storage (LibSQL/Postgres/upstash) to mastra config; storage configured but the storage package version predates the experiments store; env-gated storage config not set in the deployment.

Related errors

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