{"record":{"id":"a5dfbb6ef800892e","repo":"mastra-ai/mastra","slug":"dataset-item-identity-conflict","errorCode":"DATASET_ITEM_IDENTITY_CONFLICT","errorMessage":"error.message (DATASET_ITEM_IDENTITY_CONFLICT, cause: conflicts)","messagePattern":"error\\.message \\(DATASET_ITEM_IDENTITY_CONFLICT, cause: conflicts\\)","errorType":"error_code","errorClass":"HTTPException","httpStatus":409,"severity":"error","filePath":"packages/server/src/server/handlers/datasets.ts","lineNumber":1223,"sourceCode":"          metadata?: Record<string, unknown>;\n          source?: DatasetItemSource;\n        }>;\n      };\n      const ds = await mastra.datasets.get({ id: datasetId });\n      const addedItems = await ds.addItems({\n        items: items.map(item => ({ ...item, externalId: item.externalId ?? undefined })),\n      });\n      return { items: addedItems, count: addedItems.length };\n    } catch (error) {\n      if (isSchemaValidationError(error)) {\n        throw new HTTPException(400, {\n          message: error.message,\n          cause: { field: error.field, errors: error.errors },\n        });\n      }\n      if (error instanceof MastraError) {\n        if (error.id === 'DATASET_ITEM_IDENTITY_CONFLICT') {\n          throw new HTTPException(409, {\n            message: error.message,\n            cause: { conflicts: 'conflicts' in error ? error.conflicts : [] },\n          });\n        }\n        if (error.id === 'DATASET_ITEM_EXTERNAL_ID_INVALID') {\n          throw new HTTPException(400, { message: error.message, cause: { field: 'externalId' } });\n        }\n        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });\n      }\n      return handleError(error, 'Error batch inserting items');\n    }\n  },\n});\n\nexport const BATCH_DELETE_ITEMS_ROUTE = createRoute({\n  method: 'DELETE',\n  path: '/datasets/:datasetId/items/batch',\n  responseType: 'json',","sourceCodeStart":1205,"sourceCodeEnd":1241,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/datasets.ts#L1205-L1241","documentation":"When ds.addItems detects that an item's identity (e.g. externalId or unique item ID) already exists in the dataset, it throws a MastraError with id DATASET_ITEM_IDENTITY_CONFLICT. The handler maps this to HTTP 409 Conflict and includes cause.conflicts listing the conflicting entries.","triggerScenarios":"POST /datasets/:datasetId/items/batch where two items in the batch share an externalId, or an item's externalId/ID already exists in the dataset (and upsert semantics are not used).","commonSituations":"Re-running an import script that already inserted the items; duplicate externalIds inside one batch payload; two clients inserting the same external record concurrently; migrating data without deduplication.","solutions":["Inspect cause.conflicts in the 409 response to identify the duplicate externalIds/IDs.","Deduplicate the batch payload (e.g. new Map(items.map(i => [i.externalId, i])).values()) before sending.","Check for existing items via the list/search items endpoint and skip or update them instead of re-inserting.","If re-insertion is intentional, delete the existing items first or use an update/upsert path if available."],"exampleFix":"// before\nawait client.batchInsertItems(dsId, items); // 409 DATASET_ITEM_IDENTITY_CONFLICT\n// after\nconst unique = [...new Map(items.map(i => [i.externalId ?? i.id, i])).values()];\nawait client.batchInsertItems(dsId, unique);","handlingStrategy":"validation","validationCode":"const keys = items.map(i => i.externalId ?? i.id).filter(Boolean);\nif (new Set(keys).size !== keys.length) {\n  throw new Error('Duplicate externalIds/ids within batch payload');\n}\nconst existing = await fetch(`/api/datasets/${datasetId}/items?perPage=100`).then(r => r.json());\nconst existingKeys = new Set(existing.items.map(i => i.externalId ?? i.id));\nconst fresh = items.filter(i => !existingKeys.has(i.externalId ?? i.id));","typeGuard":"function hasConflicts(body: unknown): body is { message: string; cause: { conflicts: unknown[] } } {\n  return typeof body === 'object' && body !== null &&\n    (body as any).cause?.conflicts !== undefined;\n}","tryCatchPattern":"try {\n  return await batchInsertItems(datasetId, items);\n} catch (err) {\n  if (err.status === 409 && err.body?.cause?.conflicts) {\n    const conflictKeys = err.body.cause.conflicts;\n    console.warn('Identity conflicts, retrying with deduplicated batch:', conflictKeys);\n    return batchInsertItems(datasetId, items.filter(i => !conflictKeys.includes(i.externalId ?? i.id)));\n  }\n  throw err;\n}","preventionTips":["Deduplicate batches by externalId before sending.","Make import scripts idempotent: check for existing externalIds first or delete-then-insert.","Generate externalIds deterministically (hash of content) to make re-runs safe.","Handle 409 explicitly in automation rather than treating it as a generic failure."],"tags":["http-409","conflict","duplicate-key","datasets","batch-insert"],"backgroundTag":"duplicate-key-conflict","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}