mastra-ai/mastra · error · HTTPException

error.message (MastraError rethrown with mapped status in RU

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

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)

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.

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

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.

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.