mastra-ai/mastra · error · HTTPException

error.message (MastraError rethrown with mapped status in GE

Error message

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

What it means

Fallback branch of the GET_ITEM_VERSION route: any MastraError thrown by mastra.datasets.get or ds.getItem is rethrown as an HTTPException with a status code mapped from the error ID via getHttpStatusForMastraError and the original error.message preserved in the response body.

Source

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

  summary: 'Get item at specific dataset version',
  description: 'Returns the item as it existed at a specific dataset version',
  tags: ['Datasets'],
  requiresAuth: true,
  handler: async ({ mastra, datasetId, itemId, datasetVersion }) => {
    assertDatasetsAvailable();
    try {
      const ds = await mastra.datasets.get({ id: datasetId });
      const item = await ds.getItem({ itemId, version: datasetVersion });
      if (!item) {
        throw new HTTPException(404, { message: `Item ${itemId} not found at version ${datasetVersion}` });
      }
      if ((item as any).datasetId !== datasetId) {
        throw new HTTPException(404, { message: `Item not found in dataset: ${itemId}` });
      }
      return item as any;
    } catch (error) {
      if (error instanceof MastraError) {
        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });
      }
      return handleError(error, 'Error getting item version');
    }
  },
});

// ============================================================================
// Batch Operations Routes
// ============================================================================

export const BATCH_INSERT_ITEMS_ROUTE = createRoute({
  method: 'POST',
  path: '/datasets/:datasetId/items/batch',
  responseType: 'json',
  pathParamSchema: datasetIdPathParams,
  bodySchema: batchInsertItemsBodySchema,
  responseSchema: batchInsertItemsResponseSchema,
  summary: 'Batch insert items to dataset',

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Inspect error.message/HTTP status in the response to identify the mapped MastraError root cause.
  2. Verify the datasetId exists via GET /api/datasets.
  3. Ensure datasetVersion is a valid version number from GET /datasets/:datasetId/versions.
  4. Check storage backend health and configuration.
Defensive patterns

Strategy: try-catch

Validate before calling

const dsRes = await fetch(`/api/datasets/${datasetId}`).then(r => r.json());
if (!dsRes) throw new Error(`Dataset ${datasetId} not found`);
const versions = await fetch(`/api/datasets/${datasetId}/versions`).then(r => r.json());
if (!versions.versions?.some(v => v.version === datasetVersion)) {
  throw new Error(`Version ${datasetVersion} is not a valid dataset version`);
}

Type guard

function isValidVersion(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v >= 0;
}

Try / catch

try {
  const res = await fetch(`/api/datasets/${datasetId}/items/${itemId}/versions/${version}`);
  if (!res.ok) {
    const body = await res.json().catch(() => null);
    throw new Error(`getItemVersion failed (${res.status}): ${body?.message ?? res.statusText}`);
  }
  return await res.json();
} catch (err) {
  console.error(err);
  throw err;
}

Prevention

When it happens

Trigger: GET /datasets/:datasetId/items/:itemId/versions/:datasetVersion where the underlying call throws a MastraError — dataset not found, invalid version format handled in storage, storage backend failure.

Common situations: Nonexistent datasetId; malformed datasetVersion slipping past path validation into storage; storage adapter connection failures; datasets domain not configured in the deployment.

Related errors

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