mastra-ai/mastra · error · HTTPException

Experiments storage not available

Error message

Experiments storage not available

What it means

This HTTPException(500) is thrown by the LIST_EXPERIMENTS route handler in packages/server/src/server/handlers/datasets.ts when the configured Mastra storage does not provide an 'experiments' domain store. The server requires an experiments-backed storage class (e.g. Postgres/LibSQL with experiments support); a storage backend without that store cannot serve experiment listing. It is a server-configuration problem, not a client error.

Source

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

  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

1. Configure a storage backend that implements the experiments store (e.g. @mastra/pg or @mastra/libsql) in the Mastra instance.
2. Upgrade the storage package to a version that supports the experiments domain.
3. Verify with a runtime check that await storage.getStore('experiments') resolves before deploying routes that depend on it.

Example fix

// before
new Mastra({ storage: new InMemoryStorage() });
// after
import { MastraStorage } from '@mastra/pg';
new Mastra({ storage: new MastraStorage({ connectionString: process.env.DATABASE_URL }) });

const storage = mastra.getStorage();
const experimentsStore = storage ? await storage.getStore('experiments') : undefined;
if (!experimentsStore) {
  throw new Error('Server storage does not support experiments; configure @mastra/pg or @mastra/libsql');
}

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

try {
  const res = await fetch('/api/datasets/experiments');
  if (res.status === 500) {
    const body = await res.text();
    if (body.includes('Experiments storage not available')) {
      // surface a config-level failure, not a transient error
    }
  }
} catch (e) { /* network */ }

When it happens

Trigger: GET the experiments list endpoint when mastra.getStorage() returns a valid storage instance but await storage.getStore('experiments') returns undefined — i.e. the storage class in use does not implement the experiments store.

Common situations: Mastra configured with an in-memory or minimal storage class that lacks experiments support; older storage package versions predating the experiments store; forgetting to pass a storage class to Mastra's storage option (only caught earlier when storage itself is null).

Related errors

• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• Storage not configured. Configure storage in Mastra instance
• ExperimentsStorage not configured.
• ScoresStorage not configured.

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