mastra-ai/mastra · error · HTTPException

error.message (MastraError rethrown with mapped status in SU

Error message

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

What it means

Rethrow site in the SUBMIT_EXPERIMENT_RESULT route (datasets.ts:913): a MastraError thrown while submitting results (status, completedAt, traceId, scores payload) is rethrown as HTTPException with the id-mapped HTTP status and the original error.message. Non-Mastra failures are collapsed into handleError's 'Error submitting experiment result'.

Source

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

          }[];
        };
      const ds = await mastra.datasets.get({ id: datasetId });
      return await ds.submitExperimentResult({
        experimentId,
        itemId,
        attempt,
        input,
        output,
        groundTruth,
        error,
        startedAt,
        completedAt,
        traceId,
        scores,
      });
    } catch (error) {
      if (error instanceof MastraError) {
        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });
      }
      return handleError(error, 'Error submitting experiment result');
    }
  },
});

export const FINALIZE_EXPERIMENT_ROUTE = createRoute({
  method: 'POST',
  path: '/datasets/:datasetId/experiments/:experimentId/finalize',
  responseType: 'json',
  pathParamSchema: datasetAndExperimentIdPathParams,
  responseSchema: experimentResponseSchema,
  summary: 'Finalize an external experiment',
  description:
    'Marks an external experiment completed. The server computes succeeded/failed/skipped counts from the persisted result rows. Idempotent: finalizing an already-completed experiment returns the stored record.',
  tags: ['Datasets'],
  requiresAuth: true,
  handler: async ({ mastra, datasetId, experimentId }) => {

View on GitHub (pinned to 75dd419e61)

Solutions

Follow the mapped status: 4xx ids indicate validate the payload (experimentId, scores shape, completedAt format); 5xx ids indicate retry after fixing storage.
Confirm the experiment exists and is still accepting results before submitting.
Add idempotent submit logic (check existing result for experimentId/itemId) to avoid duplicate/terminal-state errors.

Defensive patterns

Strategy: try-catch

Validate before calling

if (!experimentId) throw new Error('experimentId is required to submit results');
if (scores && typeof scores !== 'object') throw new Error('scores must be an object');

Type guard

function isMastraHttpError(e: unknown): e is { status: number; message: string } {
  return typeof e === 'object' && e !== null && 'status' in e && 'message' in e;
}

Try / catch

try {
  await submitExperimentResult({ experimentId, itemId, status, completedAt, traceId, scores });
} catch (e) {
  if (isMastraHttpError(e) && e.status >= 500) {
    // persist result locally and retry submit later
  }
}

Prevention

Validate the result payload (experimentId, status, scores shape) before submission.
Confirm the experiment accepts results (not deleted/completed) before submitting.
Queue and retry result submissions on 5xx to survive transient storage outages.

When it happens

Trigger: POSTing an experiment result whose validation or persistence raises a MastraError — unknown experimentId, malformed scores, invalid completedAt, or storage write failure on the result record.

Common situations: Workers submitting results after the experiment was deleted or already completed; score payloads not matching the expected schema; database connectivity loss in distributed runs.

Related errors

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