{"record":{"id":"d58e56f1e150b3f5","repo":"mastra-ai/mastra","slug":"error-message-mastraerror-rethrown-with-mapped-st","errorCode":null,"errorMessage":"error.message (MastraError rethrown with mapped status in RUN_EXPERIMENT_ITEM route)","messagePattern":"error\\.message \\(MastraError rethrown with mapped status in RUN_EXPERIMENT_ITEM route\\)","errorType":"http","errorClass":"HTTPException","httpStatus":null,"severity":"error","filePath":"packages/server/src/server/handlers/datasets.ts","lineNumber":856,"sourceCode":"  responseSchema: runExperimentItemResponseSchema,\n  summary: 'Run one experiment item',\n  description:\n    \"Executes the experiment's target against one dataset item server-side, runs the resolved scorers, and upserts the result row keyed by (experimentId, itemId, attempt). Built for caller-driven loops: a retried call converges on the same row. Requires an experiment created with a target.\",\n  tags: ['Datasets'],\n  requiresAuth: true,\n  handler: async ({ mastra, datasetId, experimentId, itemId, ...params }) => {\n    assertDatasetsAvailable();\n    try {\n      const { attempt, requestContext: rawRequestContext } = params as {\n        attempt?: number;\n        requestContext?: Record<string, unknown> | RequestContext;\n      };\n      const requestContext = rawRequestContext instanceof RequestContext ? rawRequestContext.all : rawRequestContext;\n      const ds = await mastra.datasets.get({ id: datasetId });\n      return await ds.runExperimentItem({ experimentId, itemId, attempt, requestContext });\n    } catch (error) {\n      if (error instanceof MastraError) {\n        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });\n      }\n      return handleError(error, 'Error running experiment item');\n    }\n  },\n});\n\nexport const SUBMIT_EXPERIMENT_RESULT_ROUTE = createRoute({\n  method: 'POST',\n  path: '/datasets/:datasetId/experiments/:experimentId/results',\n  responseType: 'json',\n  pathParamSchema: datasetAndExperimentIdPathParams,\n  bodySchema: submitExperimentResultBodySchema,\n  responseSchema: experimentResultResponseSchema,\n  summary: 'Submit an external experiment result',\n  description:\n    'Submits (or re-submits) one item result for an external experiment. Upsert semantics on (experimentId, itemId, attempt): a retried submission converges on a single row.',\n  tags: ['Datasets'],\n  requiresAuth: true,","sourceCodeStart":838,"sourceCodeEnd":874,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/datasets.ts#L838-L874","documentation":"Rethrow site in the RUN_EXPERIMENT_ITEM route (datasets.ts:856): when ds.runExperimentItem(...) throws a MastraError, the handler rethrows it as HTTPException with getHttpStatusForMastraError(error.id) and error.message preserved. All other errors go through handleError with the generic message 'Error running experiment item'.","triggerScenarios":"Calling the run-experiment-item endpoint with an experimentId/itemId whose lookup or execution raises a MastraError — unknown experiment or item, item already completed/locked, or storage failure fetching the item.","commonSituations":"Client retrying with a stale experimentId after the experiment was deleted; running an item whose experiment is in a terminal state; storage schema/connectivity problems during item execution.","solutions":["Treat the mapped status: 404-ish ids mean re-fetch valid experimentId/itemId; 409-ish ids mean the item state does not permit running; 5xx means check storage.","Fetch the experiment first to confirm the itemId exists and is pending.","Inspect server logs for the original MastraError id/stack if the message is ambiguous."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const exp = await getExperiment(experimentId);\nif (!exp) throw new Error(`Experiment ${experimentId} not found`);\nconst item = exp.items?.find(i => i.id === itemId);\nif (!item) throw new Error(`Item ${itemId} not found in experiment ${experimentId}`);","typeGuard":"function isRunnableItem(item: unknown): item is { id: string; status: 'pending' } {\n  return (item as any)?.status === 'pending';\n}","tryCatchPattern":"try {\n  await runExperimentItem({ experimentId, itemId, attempt });\n} catch (e) {\n  if (isMastraHttpError(e) && e.status === 404) {\n    // re-fetch experiment/item ids, they are stale\n  }\n}","preventionTips":["Always fetch the experiment to confirm itemId existence and state before running.","Never reuse experimentId/itemId pairs after deletion or completion.","Version-check client SDK against server API to keep field names aligned."],"tags":["server","error-mapping","experiments","items"],"backgroundTag":"mastra-error-mapped-to-http-status","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}