mastra-ai/mastra · error · HTTPException

Datasets require @mastra/core >= 1.4.0

Error message

Datasets require @mastra/core >= 1.4.0

What it means

The datasets handlers are feature-gated on a 'datasets' capability flag derived from the installed @mastra/core version. When the core package does not expose the datasets feature (coreFeatures lacks it), assertDatasetsAvailable throws HTTP 501 Not Implemented before any dataset route executes.

Source

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

  listItemVersionsResponseSchema,
  batchInsertItemsResponseSchema,
  batchDeleteItemsResponseSchema,
  updateExperimentResultBodySchema,
  reviewSummaryResponseSchema,
  runExperimentItemBodySchema,
  runExperimentItemResponseSchema,
  submitExperimentResultBodySchema,
} from '../schemas/datasets';
import { createRoute } from '../server-adapter/routes/route-builder';
import { handleError } from './error';

// ============================================================================
// Feature gate + local type guards
// ============================================================================

function assertDatasetsAvailable(): void {
  if (!coreFeatures.has('datasets')) {
    throw new HTTPException(501, { message: 'Datasets require @mastra/core >= 1.4.0' });
  }
}

/**
 * Recovers the caller-provided request context for a dataset item.
 *
 * Server adapters overwrite the body's `requestContext` field with the live
 * server `RequestContext` instance (so bodies cannot spoof auth context), after
 * merging the body's entries into it. Persisting that live instance as item
 * data stores internal server state and fails JSON/BSON serialization, so
 * convert it back to the plain caller-provided entries (reserved `mastra__*`
 * keys excluded) before it reaches storage.
 */
function toItemRequestContext(
  requestContext: Record<string, unknown> | RequestContext | undefined,
): Record<string, unknown> | undefined {
  if (!(requestContext instanceof RequestContext)) return requestContext;
  const entries = Object.entries(requestContext.toJSON()).filter(([key]) => !isReservedRequestContextKey(key));

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade @mastra/core to >= 1.4.0 (pnpm add @mastra/core@^1.4.0) and rebuild
2. Run pnpm install to refresh the lockfile, then rebuild core and server packages if working in the monorepo
3. Verify the resolved version with pnpm list @mastra/core and ensure no overrides/resolutions pin an older version
4. Rebuild/redeploy the server image after the upgrade so the feature gate picks up the new core

Example fix

// before
"@mastra/core": "1.3.2"
// after
"@mastra/core": "^1.4.0" // then: pnpm install && pnpm build

import { version } from '@mastra/core/package.json';
const [maj, min] = version.split('.').map(Number);
if (maj < 1 || (maj === 1 && min < 4)) {
  throw new Error(`Datasets need @mastra/core >= 1.4.0 (found ${version})`);
}

try {
  const datasets = await client.listDatasets();
} catch (e) {
  if (e.status === 501) {
    console.error('Upgrade @mastra/core to >= 1.4.0 to use datasets');
  }
  throw e;
}

When it happens

Trigger: Calling any datasets route (list/create/get/update/delete datasets or list items) while the workspace resolves @mastra/core older than 1.4.0, so the 'datasets' feature flag is absent.

Common situations: Lockfile pinning @mastra/core < 1.4.0 while @mastra/server was upgraded; pnpm workspace with a stale build of core; deployment image built before a core upgrade; LLM/agent-generated package.json leaving the pinned version untouched.

Related errors

• Channels require a newer version of @mastra/core
• Item ${itemId} not found at version ${datasetVersion}
• DATASETS_STORAGE_NOT_CONFIGURED
• DATASETS_STORE_NOT_AVAILABLE
• DATASET_NOT_FOUND

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