mastra-ai/mastra · error · HTTPException

error.message (MastraError rethrown with mapped status in BA

Error message

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

What it means

Catch-all branch of the BATCH_INSERT_ITEMS route: any MastraError not matched by the schema-validation, IDENTITY_CONFLICT, or EXTERNAL_ID_INVALID special cases is rethrown as an HTTPException with a status mapped from the error ID via getHttpStatusForMastraError and the original error.message in the body.

Source

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

      return { items: addedItems, count: addedItems.length };
    } catch (error) {
      if (isSchemaValidationError(error)) {
        throw new HTTPException(400, {
          message: error.message,
          cause: { field: error.field, errors: error.errors },
        });
      }
      if (error instanceof MastraError) {
        if (error.id === 'DATASET_ITEM_IDENTITY_CONFLICT') {
          throw new HTTPException(409, {
            message: error.message,
            cause: { conflicts: 'conflicts' in error ? error.conflicts : [] },
          });
        }
        if (error.id === 'DATASET_ITEM_EXTERNAL_ID_INVALID') {
          throw new HTTPException(400, { message: error.message, cause: { field: 'externalId' } });
        }
        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });
      }
      return handleError(error, 'Error batch inserting items');
    }
  },
});

export const BATCH_DELETE_ITEMS_ROUTE = createRoute({
  method: 'DELETE',
  path: '/datasets/:datasetId/items/batch',
  responseType: 'json',
  pathParamSchema: datasetIdPathParams,
  bodySchema: batchDeleteItemsBodySchema,
  responseSchema: batchDeleteItemsResponseSchema,
  summary: 'Batch delete items from dataset',
  description: 'Deletes multiple items from the dataset in a single operation (single version entry)',
  tags: ['Datasets'],
  requiresAuth: true,
  handler: async ({ mastra, datasetId, ...params }) => {

View on GitHub (pinned to 75dd419e61)

Solutions

Use the response's HTTP status and error.message to identify the mapped MastraError root cause.
Confirm the datasetId exists via GET /api/datasets.
Verify storage backend connectivity and configuration.
Retry only for transient storage errors after confirming the request payload is valid.

Defensive patterns

Strategy: try-catch

Validate before calling

const datasets = await fetch('/api/datasets').then(r => r.json());
if (!datasets.datasets?.some(d => d.id === datasetId)) {
  throw new Error(`Dataset ${datasetId} not found before batch insert`);
}

Type guard

function isHttpErrorWithMessage(body: unknown): body is { message: string } {
  return typeof body === 'object' && body !== null && typeof (body as any).message === 'string';
}

Try / catch

try {
  return await batchInsertItems(datasetId, items);
} catch (err) {
  if (isTransient(err.status)) { // 503/502/timeout from mapped storage errors
    await sleep(backoff);
    return batchInsertItems(datasetId, items);
  }
  console.error(`batch insert failed (${err.status}): ${err.body?.message}`);
  throw err;
}

Prevention

Validate the datasetId exists before batch writes.
Validate the payload against the dataset schemas and ID rules first so only genuine infra errors remain.
Check storage backend connectivity/config in health checks.
Only retry on clearly transient statuses; treat 400/404/409 as code bugs.

When it happens

Trigger: POST /datasets/:datasetId/items/batch where ds.addItems or mastra.datasets.get throws any other MastraError — dataset not found, storage backend failure, feature unavailable, etc.

Common situations: Batch inserting into a nonexistent datasetId; storage adapter (LibSQL/PG) connection problems; datasets domain not registered in the deployment so assertDatasetsAvailable-adjacent storage calls fail; permission/auth failures surfaced as MastraError.

Related errors

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