{"record":{"id":"a658bb8a8a1c9624","repo":"mastra-ai/mastra","slug":"dataset-item-not-found","errorCode":"DATASET_ITEM_NOT_FOUND","errorMessage":"Item ${args.itemId} not found in dataset ${this.id} at version ${experiment.datasetVersion}","messagePattern":"Item (.+?) not found in dataset (.+?) at version (.+?)","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/datasets/dataset.ts","lineNumber":850,"sourceCode":"      });\n    }\n    if (experiment.status === 'completed' || experiment.status === 'failed') {\n      throw new MastraError({\n        id: 'EXPERIMENT_ALREADY_FINALIZED',\n        text: `Experiment ${args.experimentId} is already ${experiment.status}; no further items can be run`,\n        domain: 'STORAGE',\n        category: 'USER',\n      });\n    }\n\n    const datasetsStore = await this.#getDatasetsStore();\n    const dataset = await datasetsStore.getDatasetById({ id: this.id, filters: this.#scope });\n    const item = await datasetsStore.getItemById({\n      id: args.itemId,\n      datasetVersion: experiment.datasetVersion ?? undefined,\n    });\n    if (!item || item.datasetId !== this.id) {\n      throw new MastraError({\n        id: 'DATASET_ITEM_NOT_FOUND',\n        text: `Item ${args.itemId} not found in dataset ${this.id} at version ${experiment.datasetVersion}`,\n        domain: 'STORAGE',\n        category: 'USER',\n      });\n    }\n\n    return executeExperimentItem({\n      mastra: this.#mastra,\n      experiment,\n      item: {\n        id: item.id,\n        datasetVersion: item.datasetVersion,\n        input: item.input,\n        groundTruth: item.groundTruth,\n        expectedTrajectory: item.expectedTrajectory as TrajectoryExpectation | undefined,\n        requestContext: item.requestContext,\n        metadata: item.metadata,","sourceCodeStart":832,"sourceCodeEnd":868,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/datasets/dataset.ts#L832-L868","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the itemId exists in this dataset at experiment.datasetVersion before running","Use the current version's item list (dataset.getItems) instead of stale ids","Create a new experiment against the current dataset version if items changed","Confirm you are using the correct Dataset instance (id matches the item's datasetId)"],"exampleFix":"// before\nawait dataset.runExperimentItem({ experimentId: 'exp-1', itemId: staleId });\n// after\nconst items = await dataset.getItems({ version: exp.datasetVersion });\nfor (const item of items) {\n  await dataset.runExperimentItem({ experimentId: 'exp-1', itemId: item.id });\n}","handlingStrategy":"validation","validationCode":"const item = await datasetsStore.getItemById({ id: itemId, datasetVersion: experiment.datasetVersion ?? undefined });\nif (!item || item.datasetId !== dataset.id) throw new Error(`Item ${itemId} not in dataset ${dataset.id} @ v${experiment.datasetVersion}`);","typeGuard":"function isItemInDataset(item, datasetId) { return item !== null && item !== undefined && item.datasetId === datasetId; }","tryCatchPattern":"try {\n  await dataset.runExperimentItem(args);\n} catch (e) {\n  if (isMastraError(e) && e.id === 'DATASET_ITEM_NOT_FOUND') {\n    // refresh item list for experiment.datasetVersion and skip/report this item\n  } else throw e;\n}","preventionTips":["Iterate items fetched at the experiment's datasetVersion, not cached ids","Re-create experiments when the dataset is edited significantly","Validate item ids belong to the same dataset instance you call methods on"],"tags":["storage","experiments","not-found","versioning"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}