What causes "Dataset not found: ${this.id}" in mastra-ai/mastra?

Verify the dataset id exists in storage (list datasets or query the datasets table).

mastra-ai/mastra · error · MastraError

DATASET_NOT_FOUND

DATASET_NOT_FOUND

Error message

Dataset not found: ${this.id}

What it means

#assertScope() verifies the Dataset still exists within its configured scope filters before item/version/experiment operations. DATASET_NOT_FOUND is thrown when getDatasetById with the dataset id and scope filters returns no record. This is a user-facing existence check, not a corruption signal.

Source

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

    this.#experimentsStore = store;
    return store;
  }

  /**
   * Preflight tenancy gate for storage APIs whose signatures don't accept
   * `filters`. When the handle has a `#scope`, a scoped `getDatasetById` is
   * used to prove the dataset exists in the caller's tenancy; on miss we
   * throw NOT_FOUND, mirroring {@link Dataset.getDetails}. Callers that must
   * return a non-throwing empty result (e.g. list endpoints) should catch and
   * translate.
   */
  async #assertScope(): Promise<void> {
    if (!this.#scope) return;
    const store = await this.#getDatasetsStore();
    const record = await store.getDatasetById({ id: this.id, filters: this.#scope });
    if (!record) {
      throw new MastraError({
        id: 'DATASET_NOT_FOUND',
        text: `Dataset not found: ${this.id}`,
        domain: 'STORAGE',
        category: 'USER',
      });
    }
  }

  /**
   * Ownership gate: verifies a child record's `datasetId` matches `this.id`.
   * Prevents a valid scoped handle from reading/mutating child records
   * (items, experiments, results) that live under a different dataset — even
   * one in the same tenant. Returns `null` when the record is missing or
   * belongs to a different dataset, so callers can either return null or
   * translate to NOT_FOUND depending on their contract.
   */
  #ownsChild<T extends { datasetId?: string | null }>(record: T | null | undefined): T | null {
    if (!record) return null;

View on GitHub (pinned to 75dd419e61)

Solutions

Verify the dataset id exists in storage (list datasets or query the datasets table).
Check the scope filters passed to the Dataset — relax or correct them so the record matches.
Recreate the dataset or re-fetch a fresh Dataset instance via the Mastra datasets API before operating on it.

Example fix

// before
const ds = mastra.getDataset('old-id');
await ds.listItems(); // DATASET_NOT_FOUND after deletion
// after
const ds = mastra.getDataset('old-id');
if (!(await mastra.listDatasets()).some(d => d.id === ds.id)) { ds = await mastra.createDataset({...}); }

Defensive patterns

Strategy: try-catch

Validate before calling

const exists = (await mastra.listDatasets?.() ?? []).some(d => d.id === dataset.id);
if (!exists) throw new Error(`Dataset ${dataset.id} missing before operation`);

Type guard

null

Try / catch

try { await dataset.getItem(id); } catch (e) { if (e?.id === 'DATASET_NOT_FOUND') return null; throw e; }

Prevention

Re-fetch Dataset handles after deletions instead of caching them
Confirm scope filters match how the dataset was created
Guard long-lived Dataset references with periodic existence checks

When it happens

Trigger: Calling getItem, listItems, listVersions, getItemHistory, listExperiments (or internal #assertExperimentOwnership) on a Dataset whose id was deleted, or whose id does not match the current scope filters.

Common situations: Holding a Dataset object across a delete; constructing a Dataset with a mistyped id; scope filters (e.g. tenant/agent scoping) excluding the dataset; storage wiped between runs.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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