mastra-ai/mastra · error · HTTPException

error.message (MastraError rethrown with mapped status in…

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.

Solutions

  1. Use the response's HTTP status and error.message to identify the mapped MastraError root cause.
  2. Confirm the datasetId exists via GET /api/datasets.
  3. Verify storage backend connectivity and configuration.
  4. 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

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.

Appendix: 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)