mastra-ai/mastra · error · MastraError

DATASET_ITEM_NOT_FOUND

DATASET_ITEM_NOT_FOUND

Error message

Item ${args.itemId} not found in dataset ${this.id} at version ${experiment.datasetVersion}

What it means

runExperimentItem looks up the dataset item by id at the experiment's recorded datasetVersion. If no item with that id exists in this dataset at that version (or it belongs to another dataset), the item cannot be evaluated and the error is thrown.

Source

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

      });
    }
    if (experiment.status === 'completed' || experiment.status === 'failed') {
      throw new MastraError({
        id: 'EXPERIMENT_ALREADY_FINALIZED',
        text: `Experiment ${args.experimentId} is already ${experiment.status}; no further items can be run`,
        domain: 'STORAGE',
        category: 'USER',
      });
    }

    const datasetsStore = await this.#getDatasetsStore();
    const dataset = await datasetsStore.getDatasetById({ id: this.id, filters: this.#scope });
    const item = await datasetsStore.getItemById({
      id: args.itemId,
      datasetVersion: experiment.datasetVersion ?? undefined,
    });
    if (!item || item.datasetId !== this.id) {
      throw new MastraError({
        id: 'DATASET_ITEM_NOT_FOUND',
        text: `Item ${args.itemId} not found in dataset ${this.id} at version ${experiment.datasetVersion}`,
        domain: 'STORAGE',
        category: 'USER',
      });
    }

    return executeExperimentItem({
      mastra: this.#mastra,
      experiment,
      item: {
        id: item.id,
        datasetVersion: item.datasetVersion,
        input: item.input,
        groundTruth: item.groundTruth,
        expectedTrajectory: item.expectedTrajectory as TrajectoryExpectation | undefined,
        requestContext: item.requestContext,
        metadata: item.metadata,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the itemId exists in this dataset at experiment.datasetVersion before running
2. Use the current version's item list (dataset.getItems) instead of stale ids
3. Create a new experiment against the current dataset version if items changed
4. Confirm you are using the correct Dataset instance (id matches the item's datasetId)

Example fix

// before
await dataset.runExperimentItem({ experimentId: 'exp-1', itemId: staleId });
// after
const items = await dataset.getItems({ version: exp.datasetVersion });
for (const item of items) {
  await dataset.runExperimentItem({ experimentId: 'exp-1', itemId: item.id });
}

const item = await datasetsStore.getItemById({ id: itemId, datasetVersion: experiment.datasetVersion ?? undefined });
if (!item || item.datasetId !== dataset.id) throw new Error(`Item ${itemId} not in dataset ${dataset.id} @ v${experiment.datasetVersion}`);

function isItemInDataset(item, datasetId) { return item !== null && item !== undefined && item.datasetId === datasetId; }

try {
  await dataset.runExperimentItem(args);
} catch (e) {
  if (isMastraError(e) && e.id === 'DATASET_ITEM_NOT_FOUND') {
    // refresh item list for experiment.datasetVersion and skip/report this item
  } else throw e;
}

When it happens

Trigger: Calling runExperimentItem with an itemId that was deleted, belongs to a different dataset, or exists only in a newer dataset version than experiment.datasetVersion; passing a malformed/typo'd item id.

Common situations: Dataset edited (items added/removed) after the experiment pinned a version; iterating items from another dataset; hardcoding item ids from an old export; multi-tenant scope filters hiding the item.

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

• Version-control repository not found.
• Project repository not found for this organization.
• Source-control connection not found for this organization.
• Repository not found for this organization.
• Source-control installation not found for this organization.

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