mastra-ai/mastra · error · HTTPException

Item not found: ${itemId}

Error message

Item not found: ${itemId}

What it means

HTTP 404 thrown by the get-dataset-item handler. After fetching the dataset and the requested item, the handler verifies the item exists AND that its `datasetId` matches the path's datasetId; if either check fails it throws `Item not found: <itemId>`. The library throws it to avoid leaking items that exist but belong to a different dataset.

Source

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

});

export const GET_ITEM_ROUTE = createRoute({
  method: 'GET',
  path: '/datasets/:datasetId/items/:itemId',
  responseType: 'json',
  pathParamSchema: datasetAndItemIdPathParams,
  responseSchema: datasetItemResponseSchema.nullable(),
  summary: 'Get dataset item by ID',
  description: 'Returns details for a specific dataset item',
  tags: ['Datasets'],
  requiresAuth: true,
  handler: async ({ mastra, datasetId, itemId }) => {
    assertDatasetsAvailable();
    try {
      const ds = await mastra.datasets.get({ id: datasetId });
      const item = await ds.getItem({ itemId });
      if (!item || (item as any).datasetId !== datasetId) {
        throw new HTTPException(404, { message: `Item not found: ${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 dataset item');
    }
  },
});

export const UPDATE_ITEM_ROUTE = createRoute({
  method: 'PATCH',
  path: '/datasets/:datasetId/items/:itemId',
  responseType: 'json',
  pathParamSchema: datasetAndItemIdPathParams,
  bodySchema: updateItemBodySchema,
  responseSchema: datasetItemResponseSchema,

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Confirm the itemId exists via GET /api/datasets/:datasetId/items and copy the exact id.
  2. Verify the item belongs to the dataset in the URL — if it lives in another dataset, call that dataset's route instead.
  3. Re-fetch the item after deletion/re-generation flows instead of reusing stored ids.
  4. Check tenant/requestContext headers match the context the item was created under.

Example fix

// before
const item = await api.getDatasetItem('ds_1', 'item_from_ds_2');
// after
const list = await api.listDatasetItems('ds_1');
const item = list.items.find(i => i.id === 'item_from_ds_2');
if (!item) throw new Error('item_from_ds_2 is not in ds_1');
Defensive patterns

Strategy: try-catch

Validate before calling

const list = await api.listDatasetItems(datasetId);
if (!list.items.some(i => i.id === itemId)) {
  throw new Error(`Item ${itemId} not in dataset ${datasetId}`);
}

Type guard

function isNotFound(e: unknown): e is { status: 404 } {
  return typeof e === 'object' && e !== null && (e as any).status === 404;
}

Try / catch

try {
  item = await api.getDatasetItem(datasetId, itemId);
} catch (e) {
  if (isNotFound(e)) item = null; // render empty state instead of crashing
  else throw e;
}

Prevention

When it happens

Trigger: GET /api/datasets/:datasetId/items/:itemId where the itemId does not exist, the item was deleted, or the item belongs to a different dataset than the one in the URL.

Common situations: Using an itemId from another dataset after copy-pasting between handlers/tests; stale cached item references after the item was deleted; tenant/request-context scoping making the item invisible; typos in the item id.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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