{"record":{"id":"75fd0883bd863014","repo":"mastra-ai/mastra","slug":"dataset-item-external-id-invalid","errorCode":"DATASET_ITEM_EXTERNAL_ID_INVALID","errorMessage":"Dataset item externalId must be a non-empty string.","messagePattern":"Dataset item externalId must be a non-empty string\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/datasets/identity.ts","lineNumber":132,"sourceCode":"      } satisfies DatasetItemRow;\n      if (!datasetItemPayloadsEqual(item, acceptedRow)) {\n        conflicts.push({ index, externalId: item.externalId, existingItemId: local.id, reason: 'payload_mismatch' });\n      }\n      resolvedIds.push(local.id);\n      continue;\n    }\n    const insert = { id: createId(), item };\n    inserts.push(insert);\n    requestLocal.set(item.externalId, insert);\n    resolvedIds.push(insert.id);\n  }\n  if (conflicts.length) throw createDatasetItemIdentityConflictError(conflicts);\n  return { inserts, resolvedIds, existingCurrentItems };\n}\n\nexport function validateDatasetItemExternalId(externalId: string | undefined): void {\n  if (externalId === '') {\n    throw new MastraError({\n      id: 'DATASET_ITEM_EXTERNAL_ID_INVALID',\n      text: 'Dataset item externalId must be a non-empty string.',\n      domain: 'STORAGE',\n      category: 'USER',\n    });\n  }\n}\n","sourceCodeStart":114,"sourceCodeEnd":140,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/datasets/identity.ts#L114-L140","documentation":"validateDatasetItemExternalId() (a MastraError with id DATASET_ITEM_EXTERNAL_ID_INVALID, domain STORAGE, category USER) rejects an items' externalId of exactly '' (empty string). Undefined/absent externalId is allowed (auto-generated id is used), but an explicit empty string is treated as a caller bug since externalIds are identity keys.","triggerScenarios":"addItems()/batchInsertItems() with an item like {externalId: '', input, ...} — typically externalId sourced from an empty form field, empty request property, or `String(value)` of null/'' upstream.","commonSituations":"Importing rows from CSV/spreadsheets where a key column is blank, copying user input straight into externalId, or template code that defaults `externalId: something || ''`.","solutions":["Omit externalId entirely when you have none, so the library generates an id.","Generate a real externalId before inserting (e.g. crypto.randomUUID() or a domain key).","Validate/coerce input upstream: trim and reject blank keys before building the batch.","Note that undefined passes but '' throws — normalize '' to undefined, never to a placeholder string."],"exampleFix":"// before\nawait storage.datasets.addItems({ datasetId: 'ds', items: [{ externalId: row.key || '', input: row.data }] });\n// after\nconst externalId = row.key?.trim() || undefined; // undefined -> generated id\nawait storage.datasets.addItems({ datasetId: 'ds', items: [{ externalId, input: row.data }] });","handlingStrategy":"validation","validationCode":"for (const item of items) {\n  if (item.externalId === '') throw new Error(`items[${items.indexOf(item)}].externalId must be non-empty or omitted`);\n}","typeGuard":"function hasValidExternalId(item: { externalId?: string }): boolean {\n  return item.externalId === undefined || item.externalId.length > 0;\n}","tryCatchPattern":"try {\n  await storage.datasets.addItems({ datasetId, items });\n} catch (e) {\n  if (e?.id === 'DATASET_ITEM_EXTERNAL_ID_INVALID') {\n    // report the offending payload to the caller / fix upstream input\n  } else throw e;\n}","preventionTips":["Trim and normalize key fields at the ingestion boundary; convert '' to undefined.","Use generated ids (omit externalId) unless you have a real domain key.","Add a schema check on imports (CSV/JSON) that rejects blank key columns."],"tags":["storage","datasets","validation","user-input"],"backgroundTag":"invalid-argument","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}