mastra-ai/mastra · error · MastraError

DATASETS_STORAGE_NOT_CONFIGURED

DATASETS_STORAGE_NOT_CONFIGURED

Error message

Storage not configured. Configure storage in Mastra instance.

What it means

The Dataset class resolves its datasets storage domain through the Mastra instance. This MastraError (DATASETS_STORAGE_NOT_CONFIGURED, STORAGE/USER) is thrown when no storage is configured on the Mastra instance, so there is nowhere to read/write dataset records. It is a user configuration error surfaced on first storage access.

Source

Thrown at packages/core/src/datasets/dataset.ts:69

   */
  #scope?: DatasetTenancyFilters;

  constructor(id: string, mastra: Mastra, scope?: DatasetTenancyFilters) {
    this.id = id;
    this.#mastra = mastra;
    this.#scope = scope;
  }

  // ---------------------------------------------------------------------------
  // Lazy storage resolution
  // ---------------------------------------------------------------------------

  async #getDatasetsStore(): Promise<DatasetsStorage> {
    if (this.#datasetsStore) return this.#datasetsStore;

    const storage = this.#mastra.getStorage();
    if (!storage) {
      throw new MastraError({
        id: 'DATASETS_STORAGE_NOT_CONFIGURED',
        text: 'Storage not configured. Configure storage in Mastra instance.',
        domain: 'STORAGE',
        category: 'USER',
      });
    }

    const store = await storage.getStore('datasets');
    if (!store) {
      throw new MastraError({
        id: 'DATASETS_STORE_NOT_AVAILABLE',
        text: 'Datasets store not available. Ensure your storage adapter provides a datasets domain.',
        domain: 'STORAGE',
        category: 'USER',
      });
    }

    this.#datasetsStore = store;

View on GitHub (pinned to 75dd419e61)

Solutions

Configure storage on your Mastra instance: new Mastra({ storage: new MastraStorage(...) }).
Use a storage adapter that supports the datasets domain (e.g. libsql, pg, upstash).
Verify getStorage() on your Mastra instance returns a value before using Dataset APIs.

Example fix

// before
const mastra = new Mastra({ agents });
// after
const mastra = new Mastra({ agents, storage: new MastraLibsqlStorage({ url: 'file:./mastra.db' }) });

Defensive patterns

Strategy: validation

Validate before calling

if (!mastra.getStorage()) throw new Error('Configure storage on the Mastra instance before using Dataset APIs');

Type guard

null

Try / catch

try { await dataset.listItems(); } catch (e) { if (e?.id === 'DATASETS_STORAGE_NOT_CONFIGURED') { /* surface config error */ } else throw e; }

Prevention

Always pass storage when constructing Mastra in any project that uses datasets
Add a startup assertion that mastra.getStorage() is truthy
Use a shared Mastra factory so storage config cannot be omitted

When it happens

Trigger: Calling any Dataset API (store, datasetsStore, item/versions/experiments methods) on a Mastra instance created without a `storage` option, and #getDatasetsStore() finding this.#mastra.getStorage() returns undefined.

Common situations: Constructing `new Mastra()` without storage in scripts or examples; forgetting storage when copying a minimal agent setup; storage removed during a refactor while Dataset usage remained.

Related errors

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