mastra-ai/mastra · error · HTTPException

Item ${itemId} not found at version ${datasetVersion}

Error message

Item ${itemId} not found at version ${datasetVersion}

What it means

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.

Source

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

});

export const GET_ITEM_VERSION_ROUTE = createRoute({
  method: 'GET',
  path: '/datasets/:datasetId/items/:itemId/versions/:datasetVersion',
  responseType: 'json',
  pathParamSchema: datasetItemVersionPathParams,
  responseSchema: datasetItemResponseSchema.nullable(),
  summary: 'Get item at specific dataset version',
  description: 'Returns the item as it existed at a specific dataset version',
  tags: ['Datasets'],
  requiresAuth: true,
  handler: async ({ mastra, datasetId, itemId, datasetVersion }) => {
    assertDatasetsAvailable();
    try {
      const ds = await mastra.datasets.get({ id: datasetId });
      const item = await ds.getItem({ itemId, version: datasetVersion });
      if (!item) {
        throw new HTTPException(404, { message: `Item ${itemId} not found at version ${datasetVersion}` });
      }
      if ((item as any).datasetId !== datasetId) {
        throw new HTTPException(404, { message: `Item not found in dataset: ${itemId}` });
      }
      return item as any;
    } catch (error) {
      if (error instanceof MastraError) {
        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });
      }
      return handleError(error, 'Error getting item version');
    }
  },
});

// ============================================================================
// Batch Operations Routes
// ============================================================================

View on GitHub (pinned to 75dd419e61)

Solutions

1. Confirm the version number via GET /api/datasets/:datasetId/versions and pick a version at or after the item's creation.
2. Use the item's history endpoint (GET .../items/:itemId/history) to find versions where the item exists.
3. Check that the itemId is correct for this dataset.
4. If the item should exist at that version, verify the dataset history wasn't truncated or recreated.

Example fix

// before
const item = await client.getDatasetItemVersion(dsId, itemId, 3); // 404: not at version 3
// after
const { versions } = await client.listDatasetVersions(dsId);
const latest = versions[0]?.version;
const item = await client.getDatasetItemVersion(dsId, itemId, latest);

const { versions } = await fetch(`/api/datasets/${datasetId}/versions`).then(r => r.json());
const history = await fetch(`/api/datasets/${datasetId}/items/${itemId}/history`).then(r => r.json());
const available = new Set((history.history ?? []).map(h => h.version ?? h.datasetVersion));
if (!available.has(datasetVersion)) {
  throw new Error(`Item ${itemId} has no snapshot at version ${datasetVersion}; available: ${[...available].join(',')}`);
}

function isVersionAvailableForItem(
  history: Array<{ version?: number; datasetVersion?: number }>,
  version: number
): boolean {
  return history.some(h => (h.version ?? h.datasetVersion) === version);
}

try {
  const res = await fetch(`/api/datasets/${datasetId}/items/${itemId}/versions/${version}`);
  if (res.status === 404) return null; // item absent at that version is a normal outcome
  if (!res.ok) throw new Error(await res.text());
  return await res.json();
} catch (err) {
  console.error('getItemVersion failed', err);
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Dataset item identity history is corrupt for externalId: ${r
• Datasets require @mastra/core >= 1.4.0
• Item not found: ${itemId}
• Item not found in dataset: ${itemId}
• Version with id ${from} not found

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