mastra-ai/mastra · error · HTTPException

error.message (MastraError rethrown with mapped status in…

Error message

error.message (MastraError rethrown with mapped status in RUN_EXPERIMENT_ITEM route)

What it means

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'.

Solutions

  1. 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.
  2. Fetch the experiment first to confirm the itemId exists and is pending.
  3. Inspect server logs for the original MastraError id/stack if the message is ambiguous.
Defensive patterns

Strategy: validation

Validate before calling

const exp = await getExperiment(experimentId);
if (!exp) throw new Error(`Experiment ${experimentId} not found`);
const item = exp.items?.find(i => i.id === itemId);
if (!item) throw new Error(`Item ${itemId} not found in experiment ${experimentId}`);

Type guard

function isRunnableItem(item: unknown): item is { id: string; status: 'pending' } {
  return (item as any)?.status === 'pending';
}

Try / catch

try {
  await runExperimentItem({ experimentId, itemId, attempt });
} catch (e) {
  if (isMastraHttpError(e) && e.status === 404) {
    // re-fetch experiment/item ids, they are stale
  }
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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

Appendix: source

Thrown at packages/server/src/server/handlers/datasets.ts:856

  responseSchema: runExperimentItemResponseSchema,
  summary: 'Run one experiment item',
  description:
    "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.",
  tags: ['Datasets'],
  requiresAuth: true,
  handler: async ({ mastra, datasetId, experimentId, itemId, ...params }) => {
    assertDatasetsAvailable();
    try {
      const { attempt, requestContext: rawRequestContext } = params as {
        attempt?: number;
        requestContext?: Record<string, unknown> | RequestContext;
      };
      const requestContext = rawRequestContext instanceof RequestContext ? rawRequestContext.all : rawRequestContext;
      const ds = await mastra.datasets.get({ id: datasetId });
      return await ds.runExperimentItem({ experimentId, itemId, attempt, requestContext });
    } catch (error) {
      if (error instanceof MastraError) {
        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });
      }
      return handleError(error, 'Error running experiment item');
    }
  },
});

export const SUBMIT_EXPERIMENT_RESULT_ROUTE = createRoute({
  method: 'POST',
  path: '/datasets/:datasetId/experiments/:experimentId/results',
  responseType: 'json',
  pathParamSchema: datasetAndExperimentIdPathParams,
  bodySchema: submitExperimentResultBodySchema,
  responseSchema: experimentResultResponseSchema,
  summary: 'Submit an external experiment result',
  description:
    '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.',
  tags: ['Datasets'],
  requiresAuth: true,

View on GitHub (pinned to 75dd419e61)