mastra-ai/mastra · error · MastraError

EXPERIMENTS_STORAGE_NOT_CONFIGURED

EXPERIMENTS_STORAGE_NOT_CONFIGURED

Error message

ExperimentsStorage not configured. Configure storage in the Mastra instance.

What it means

executeExperimentItem needs the experiments storage domain to persist item status and scores, and resolves it BEFORE executing the target so misconfiguration fails fast before billing or score writes. If mastra.getStorage() returns no storage or storage.getStore('experiments') returns undefined, it throws EXPERIMENTS_STORAGE_NOT_CONFIGURED.

Source

Thrown at packages/core/src/datasets/experiment/item.ts:121

    const resolution = await createItemScorerResolver(mastra)(item.scorerIds);
    scorers = resolution.scorers;
    if (resolution.missingIds.length > 0) {
      scorerConfigError = {
        code: EXPERIMENT_ITEM_SCORER_NOT_FOUND,
        message: `Item scorer configuration references unregistered scorer IDs: ${resolution.missingIds.join(', ')}`,
      };
    }
  } else {
    scorers = resolveScorers(mastra, [...new Set(args.datasetScorerIds ?? [])]);
  }

  // Resolve the experiments store before executing the target so a
  // misconfigured storage layer fails fast, before the target is billed or
  // any score rows are written.
  const storage = mastra.getStorage();
  const experimentsStore = await storage?.getStore('experiments');
  if (!experimentsStore) {
    throw new MastraError({
      id: 'EXPERIMENTS_STORAGE_NOT_CONFIGURED',
      text: 'ExperimentsStorage not configured. Configure storage in the Mastra instance.',
      domain: 'STORAGE',
      category: 'USER',
    });
  }

  const startedAt = new Date();

  const mergedRequestContext =
    args.requestContext || item.requestContext ? { ...args.requestContext, ...item.requestContext } : undefined;

  const execResult: ExecutionResult = scorerConfigError
    ? { output: null, error: scorerConfigError, traceId: null }
    : await executeTarget(resolved.target, experiment.targetType, item, {
        requestContext: mergedRequestContext,
        experimentId: experiment.id,
      });

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Configure storage: new Mastra({ storage: new MastraStorage(...) }) with an adapter that supports the experiments domain.
  2. Upgrade your storage adapter package to a version providing the experiments store.
  3. In tests, either configure an in-memory storage or skip local execution in favor of submitExperimentResult.
  4. Pre-flight check: (await mastra.getStorage()?.getStore('experiments')) before starting runs.

Example fix

// before
new Mastra({ agents: { myAgent } })
// after
new Mastra({ agents: { myAgent }, storage: new LibSQLStore({ url: process.env.DATABASE_URL }) })
Defensive patterns

Strategy: validation

Validate before calling

const store = await mastra.getStorage()?.getStore('experiments');
if (!store) throw new Error('Configure storage with an experiments domain before running experiments');

Type guard

async function hasExperimentsStore(m: Mastra): Promise<boolean> {
  return !!(await m.getStorage()?.getStore('experiments'));
}

Try / catch

try {
  await runExperimentItem({ mastra, experiment, item });
} catch (err) {
  if (err?.id === 'EXPERIMENTS_STORAGE_NOT_CONFIGURED') {
    logger.error('Add storage: new Mastra({ storage }) with experiments domain support');
  }
  throw err;
}

Prevention

When it happens

Trigger: Running an experiment with a Mastra instance constructed without storage; storage configured but the adapter does not implement the experiments domain store.

Common situations: Evaluating in-memory/test Mastra instances with no storage; using a storage adapter that predates the experiments domain; forgetting `storage:` in new Mastra({...}) for server-side experiment runs.

Related errors

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