{"record":{"id":"f5310e6b00ac6dbf","repo":"mastra-ai/mastra","slug":"experiment-already-finalized","errorCode":"EXPERIMENT_ALREADY_FINALIZED","errorMessage":"Experiment ${args.experimentId} is already ${experiment.status}; no further items can be run","messagePattern":"Experiment (.+?) is already (.+?); no further items can be run","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/datasets/dataset.ts","lineNumber":835,"sourceCode":"  async runExperimentItem(args: {\n    experimentId: string;\n    itemId: string;\n    /** Zero-based repetition index for repeated trials. Defaults to `0`. */\n    attempt?: number;\n    /** Request context merged with the item's own request context (item wins). */\n    requestContext?: Record<string, unknown>;\n  }): Promise<{ result: ExperimentResult; scores: Awaited<ReturnType<typeof executeExperimentItem>>['scores'] }> {\n    const experiment = await this.#getOwnedExperiment(args.experimentId);\n    if (experiment.targetType === null) {\n      throw new MastraError({\n        id: 'EXPERIMENT_HAS_NO_TARGET',\n        text: `Experiment ${args.experimentId} has no target; ingest results via submitExperimentResult instead`,\n        domain: 'STORAGE',\n        category: 'USER',\n      });\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',","sourceCodeStart":817,"sourceCodeEnd":853,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/datasets/dataset.ts#L817-L853","documentation":"runExperimentItem refuses to execute items on an experiment whose status is already 'completed' or 'failed'. A finalized experiment is immutable; running further items would corrupt its results or scores.","triggerScenarios":"Calling runExperimentItem for an experiment whose status is 'completed' or 'failed' — e.g. all items already ran, the experiment failed earlier, or a stale client retries after finalization.","commonSituations":"Re-running an eval script without checking status; concurrent workers racing on the last item after another finalized the experiment; retry logic replaying an item against a failed experiment; resuming an old experiment id from a previous run.","solutions":["Check experiment.status before calling; skip or create a new experiment if finalized","Create a new experiment (new id) to re-run the evaluation","Handle status transitions in your runner loop: stop when status becomes completed/failed","Remove retry logic that replays items against finalized experiments"],"exampleFix":"// before\nawait dataset.runExperimentItem({ experimentId: 'exp-1', itemId: 'item-3' });\n// after\nconst exp = await getExperiment('exp-1');\nif (exp.status === 'completed' || exp.status === 'failed') {\n  exp = await dataset.createExperiment({ id: 'exp-1-rerun', ... });\n}\nawait dataset.runExperimentItem({ experimentId: exp.id, itemId: 'item-3' });","handlingStrategy":"validation","validationCode":"const exp = await getExperimentById(experimentId);\nif (exp.status === 'completed' || exp.status === 'failed') throw new Error('Experiment finalized; create a new one to re-run');","typeGuard":"function isRunnable(exp) { return exp.status !== 'completed' && exp.status !== 'failed'; }","tryCatchPattern":"try {\n  await dataset.runExperimentItem(args);\n} catch (e) {\n  if (isMastraError(e) && e.id === 'EXPERIMENT_ALREADY_FINALIZED') {\n    // stop the loop or create a fresh experiment for a re-run\n  } else throw e;\n}","preventionTips":["Check experiment.status before every item run in runner loops","Stop loops immediately when status flips to completed/failed","Use a fresh experiment id for each re-run instead of replaying finalized ones"],"tags":["storage","experiments","state-machine","user-error"],"backgroundTag":"operation-on-finalized-resource","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}