{"record":{"id":"a50e6b0dbc842957","repo":"mastra-ai/mastra","slug":"datasets-require-mastra-core-1-4-0","errorCode":null,"errorMessage":"Datasets require @mastra/core >= 1.4.0","messagePattern":"Datasets require @mastra/core >= 1\\.4\\.0","errorType":"http","errorClass":"HTTPException","httpStatus":501,"severity":"error","filePath":"packages/server/src/server/handlers/datasets.ts","lineNumber":64,"sourceCode":"  listItemVersionsResponseSchema,\n  batchInsertItemsResponseSchema,\n  batchDeleteItemsResponseSchema,\n  updateExperimentResultBodySchema,\n  reviewSummaryResponseSchema,\n  runExperimentItemBodySchema,\n  runExperimentItemResponseSchema,\n  submitExperimentResultBodySchema,\n} from '../schemas/datasets';\nimport { createRoute } from '../server-adapter/routes/route-builder';\nimport { handleError } from './error';\n\n// ============================================================================\n// Feature gate + local type guards\n// ============================================================================\n\nfunction assertDatasetsAvailable(): void {\n  if (!coreFeatures.has('datasets')) {\n    throw new HTTPException(501, { message: 'Datasets require @mastra/core >= 1.4.0' });\n  }\n}\n\n/**\n * Recovers the caller-provided request context for a dataset item.\n *\n * Server adapters overwrite the body's `requestContext` field with the live\n * server `RequestContext` instance (so bodies cannot spoof auth context), after\n * merging the body's entries into it. Persisting that live instance as item\n * data stores internal server state and fails JSON/BSON serialization, so\n * convert it back to the plain caller-provided entries (reserved `mastra__*`\n * keys excluded) before it reaches storage.\n */\nfunction toItemRequestContext(\n  requestContext: Record<string, unknown> | RequestContext | undefined,\n): Record<string, unknown> | undefined {\n  if (!(requestContext instanceof RequestContext)) return requestContext;\n  const entries = Object.entries(requestContext.toJSON()).filter(([key]) => !isReservedRequestContextKey(key));","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/datasets.ts#L46-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade @mastra/core to >= 1.4.0 (pnpm add @mastra/core@^1.4.0) and rebuild","Run pnpm install to refresh the lockfile, then rebuild core and server packages if working in the monorepo","Verify the resolved version with pnpm list @mastra/core and ensure no overrides/resolutions pin an older version","Rebuild/redeploy the server image after the upgrade so the feature gate picks up the new core"],"exampleFix":"// before\n\"@mastra/core\": \"1.3.2\"\n// after\n\"@mastra/core\": \"^1.4.0\" // then: pnpm install && pnpm build","handlingStrategy":"validation","validationCode":"import { version } from '@mastra/core/package.json';\nconst [maj, min] = version.split('.').map(Number);\nif (maj < 1 || (maj === 1 && min < 4)) {\n  throw new Error(`Datasets need @mastra/core >= 1.4.0 (found ${version})`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const datasets = await client.listDatasets();\n} catch (e) {\n  if (e.status === 501) {\n    console.error('Upgrade @mastra/core to >= 1.4.0 to use datasets');\n  }\n  throw e;\n}","preventionTips":["Pin @mastra/core to ^1.4.0 or later wherever @mastra/server is used","Audit package.json overrides/resolutions for stale core pins","Rebuild monorepo packages after core upgrades (pnpm turbo build --filter ...)","Feature-detect dataset routes before exposing them in tooling"],"tags":["versioning","http-501","feature-gate","datasets"],"backgroundTag":"feature-requires-newer-version","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}