{"record":{"id":"7da8fba73c336745","repo":"mastra-ai/mastra","slug":"item-not-found-itemid","errorCode":null,"errorMessage":"Item not found: ${itemId}","messagePattern":"Item not found: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/datasets.ts","lineNumber":493,"sourceCode":"});\n\nexport const GET_ITEM_ROUTE = createRoute({\n  method: 'GET',\n  path: '/datasets/:datasetId/items/:itemId',\n  responseType: 'json',\n  pathParamSchema: datasetAndItemIdPathParams,\n  responseSchema: datasetItemResponseSchema.nullable(),\n  summary: 'Get dataset item by ID',\n  description: 'Returns details for a specific dataset item',\n  tags: ['Datasets'],\n  requiresAuth: true,\n  handler: async ({ mastra, datasetId, itemId }) => {\n    assertDatasetsAvailable();\n    try {\n      const ds = await mastra.datasets.get({ id: datasetId });\n      const item = await ds.getItem({ itemId });\n      if (!item || (item as any).datasetId !== datasetId) {\n        throw new HTTPException(404, { message: `Item not found: ${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 dataset item');\n    }\n  },\n});\n\nexport const UPDATE_ITEM_ROUTE = createRoute({\n  method: 'PATCH',\n  path: '/datasets/:datasetId/items/:itemId',\n  responseType: 'json',\n  pathParamSchema: datasetAndItemIdPathParams,\n  bodySchema: updateItemBodySchema,\n  responseSchema: datasetItemResponseSchema,","sourceCodeStart":475,"sourceCodeEnd":511,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/datasets.ts#L475-L511","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the itemId exists via GET /api/datasets/:datasetId/items and copy the exact id.","Verify the item belongs to the dataset in the URL — if it lives in another dataset, call that dataset's route instead.","Re-fetch the item after deletion/re-generation flows instead of reusing stored ids.","Check tenant/requestContext headers match the context the item was created under."],"exampleFix":"// before\nconst item = await api.getDatasetItem('ds_1', 'item_from_ds_2');\n// after\nconst list = await api.listDatasetItems('ds_1');\nconst item = list.items.find(i => i.id === 'item_from_ds_2');\nif (!item) throw new Error('item_from_ds_2 is not in ds_1');","handlingStrategy":"try-catch","validationCode":"const list = await api.listDatasetItems(datasetId);\nif (!list.items.some(i => i.id === itemId)) {\n  throw new Error(`Item ${itemId} not in dataset ${datasetId}`);\n}","typeGuard":"function isNotFound(e: unknown): e is { status: 404 } {\n  return typeof e === 'object' && e !== null && (e as any).status === 404;\n}","tryCatchPattern":"try {\n  item = await api.getDatasetItem(datasetId, itemId);\n} catch (e) {\n  if (isNotFound(e)) item = null; // render empty state instead of crashing\n  else throw e;\n}","preventionTips":["Only use itemIds returned by list/get for the same datasetId.","Re-fetch ids after deletion or regeneration flows; never reuse stale references.","Send consistent tenant/requestContext headers so scoping matches creation context."],"tags":["http-404","not-found","datasets","rest-api"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}