mastra-ai/mastra · error · HTTPException

error.message

Error message

error.message

What it means

This is not a distinct error type but the generic rethrow path in the list-datasets route handler. When mastra.datasets.list() (or the storage layer behind it) throws a MastraError, the handler converts it to an HTTPException whose message is the underlying error.message and whose status code is derived from the error ID (getHttpStatusForMastraError). Non-MastraError failures go to handleError and surface as a generic 500. The developer-facing symptom is an HTTP response whose body text is the raw internal dataset error message.

Source

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

  responseType: 'json',
  queryParamSchema: paginationQuerySchema,
  responseSchema: listDatasetsResponseSchema,
  summary: 'List all datasets',
  description: 'Returns a paginated list of all datasets',
  tags: ['Datasets'],
  requiresAuth: true,
  handler: async ({ mastra, ...params }) => {
    assertDatasetsAvailable();
    try {
      const { page, perPage } = params;
      const result = await mastra.datasets.list({ page: page ?? 0, perPage: perPage ?? 10 });
      return {
        datasets: result.datasets as any,
        pagination: result.pagination,
      };
    } catch (error) {
      if (error instanceof MastraError) {
        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });
      }
      return handleError(error, 'Error listing datasets');
    }
  },
});

export const CREATE_DATASET_ROUTE = createRoute({
  method: 'POST',
  path: '/datasets',
  responseType: 'json',
  bodySchema: createDatasetBodySchema,
  responseSchema: datasetResponseSchema,
  summary: 'Create a new dataset',
  description: 'Creates a new dataset with the specified name and optional metadata',
  tags: ['Datasets'],
  requiresAuth: true,
  handler: async ({ mastra, ...params }) => {
    assertDatasetsAvailable();

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Read error.message in the HTTP response — it is the underlying MastraError message; fix the storage/domain issue it describes.
  2. Verify @mastra/core is >= 1.4.0 so the datasets feature is registered (the handler gates with coreFeatures.has('datasets')).
  3. Check the storage adapter connection/configuration used by mastra storage.
  4. If the error is not a MastraError it returns 500 via handleError — enable server logs to see the original stack.

Example fix

// before: response is a bare message string
const res = await fetch('/api/datasets');
const msg = await res.text();
// after: handle non-OK statuses explicitly and surface the message
if (!res.ok) {
  const { message } = await res.json();
  throw new Error(`List datasets failed (${res.status}): ${message}`);
}
Defensive patterns

Strategy: try-catch

Validate before calling

import { execSync } from 'node:child_process';
const version = JSON.parse(execSync('npm ls @mastra/core --json').toString())
  .dependencies['@mastra/core'].version;
if (version < '1.4.0') throw new Error('datasets feature requires @mastra/core >= 1.4.0');

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 {
  const res = await fetch('/api/datasets');
  if (!res.ok) {
    const body = await res.json();
    // body.message is the underlying MastraError message
    throw new DatasetApiError(res.status, body.message);
  }
  return res.json();
} catch (e) {
  if (e instanceof DatasetApiError && e.status >= 500) {
    // storage/domain failure — retry with backoff or surface infra alert
  }
  throw e;
}

Prevention

When it happens

Trigger: GET /api/datasets where the underlying storage/dataset domain throws a MastraError — e.g. a storage adapter failure, a tenant/project resolution error, or any DATASET_* / storage error ID raised while listing datasets. Also occurs when @mastra/core is below the version that registers the datasets feature and the core layer rejects the call.

Common situations: Misconfigured storage adapter (database down, wrong connection string), upgrading server packages without upgrading @mastra/core to >= 1.4.0 so the datasets domain is unavailable, or organizationId/projectId tenancy filters pointing at a nonexistent project.

Related errors

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