{"record":{"id":"95ebf01e5d23a1c9","repo":"mastra-ai/mastra","slug":"item-itemid-not-found-at-version-datasetversi","errorCode":null,"errorMessage":"Item ${itemId} not found at version ${datasetVersion}","messagePattern":"Item (.+?) not found at version (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/datasets.ts","lineNumber":1163,"sourceCode":"});\n\nexport const GET_ITEM_VERSION_ROUTE = createRoute({\n  method: 'GET',\n  path: '/datasets/:datasetId/items/:itemId/versions/:datasetVersion',\n  responseType: 'json',\n  pathParamSchema: datasetItemVersionPathParams,\n  responseSchema: datasetItemResponseSchema.nullable(),\n  summary: 'Get item at specific dataset version',\n  description: 'Returns the item as it existed at a specific dataset version',\n  tags: ['Datasets'],\n  requiresAuth: true,\n  handler: async ({ mastra, datasetId, itemId, datasetVersion }) => {\n    assertDatasetsAvailable();\n    try {\n      const ds = await mastra.datasets.get({ id: datasetId });\n      const item = await ds.getItem({ itemId, version: datasetVersion });\n      if (!item) {\n        throw new HTTPException(404, { message: `Item ${itemId} not found at version ${datasetVersion}` });\n      }\n      if ((item as any).datasetId !== datasetId) {\n        throw new HTTPException(404, { message: `Item not found in dataset: ${itemId}` });\n      }\n      return item as any;\n    } catch (error) {\n      if (error instanceof MastraError) {\n        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });\n      }\n      return handleError(error, 'Error getting item version');\n    }\n  },\n});\n\n// ============================================================================\n// Batch Operations Routes\n// ============================================================================\n","sourceCodeStart":1145,"sourceCodeEnd":1181,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/datasets.ts#L1145-L1181","documentation":"The GET_ITEM_VERSION route (GET /datasets/:datasetId/items/:itemId/versions/:datasetVersion) fetches the item as it existed at a specific dataset version (SCD-2 point-in-time lookup). If ds.getItem({ itemId, version }) returns null for that version, the handler throws a 404 naming the itemId and version.","triggerScenarios":"Call GET /api/datasets/:datasetId/items/:itemId/versions/:datasetVersion where the item did not exist at (or was not present in) that dataset version — e.g. the item was added in a later version, or the version number is wrong/out of range.","commonSituations":"Requesting version 3 for an item only introduced in version 5; off-by-one or stale version numbers cached by the client; item was deleted before that version snapshot; querying a recreated dataset whose version numbering restarted.","solutions":["Confirm the version number via GET /api/datasets/:datasetId/versions and pick a version at or after the item's creation.","Use the item's history endpoint (GET .../items/:itemId/history) to find versions where the item exists.","Check that the itemId is correct for this dataset.","If the item should exist at that version, verify the dataset history wasn't truncated or recreated."],"exampleFix":"// before\nconst item = await client.getDatasetItemVersion(dsId, itemId, 3); // 404: not at version 3\n// after\nconst { versions } = await client.listDatasetVersions(dsId);\nconst latest = versions[0]?.version;\nconst item = await client.getDatasetItemVersion(dsId, itemId, latest);","handlingStrategy":"validation","validationCode":"const { versions } = await fetch(`/api/datasets/${datasetId}/versions`).then(r => r.json());\nconst history = await fetch(`/api/datasets/${datasetId}/items/${itemId}/history`).then(r => r.json());\nconst available = new Set((history.history ?? []).map(h => h.version ?? h.datasetVersion));\nif (!available.has(datasetVersion)) {\n  throw new Error(`Item ${itemId} has no snapshot at version ${datasetVersion}; available: ${[...available].join(',')}`);\n}","typeGuard":"function isVersionAvailableForItem(\n  history: Array<{ version?: number; datasetVersion?: number }>,\n  version: number\n): boolean {\n  return history.some(h => (h.version ?? h.datasetVersion) === version);\n}","tryCatchPattern":"try {\n  const res = await fetch(`/api/datasets/${datasetId}/items/${itemId}/versions/${version}`);\n  if (res.status === 404) return null; // item absent at that version is a normal outcome\n  if (!res.ok) throw new Error(await res.text());\n  return await res.json();\n} catch (err) {\n  console.error('getItemVersion failed', err);\n  throw err;\n}","preventionTips":["Fetch the version list (or item history) instead of hardcoding version numbers.","Treat 'item not at version N' as expected for SCD-2 data — handle null results gracefully.","Track item creation version when storing client-side references.","Avoid reusing version numbers from a different/older dataset instance."],"tags":["http-404","datasets","versioning","scd2"],"backgroundTag":"resource-version-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}