{"record":{"id":"17c52cf57fa512d2","repo":"mastra-ai/mastra","slug":"dataset-id-conflict","errorCode":"DATASET_ID_CONFLICT","errorMessage":"Dataset ID \"${input.id}\" is already in use with incompatible immutable fields","messagePattern":"Dataset ID \"(.+?)\" is already in use with incompatible immutable fields","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/datasets/base.ts","lineNumber":66,"sourceCode":"      throw new MastraError({\n        id: 'DATASET_INVALID_ID',\n        domain: ErrorDomain.STORAGE,\n        category: ErrorCategory.USER,\n        details: { id },\n        text: 'Caller-defined dataset ID must not be empty',\n      });\n    }\n  }\n\n  /**\n   * Returns an existing dataset when a caller-defined ID is reused compatibly.\n   * Optional immutable fields normalize omitted and null values to the same value.\n   */\n  protected resolveExistingDataset(existing: DatasetRecord, input: CreateDatasetInput & { id: string }): DatasetRecord {\n    const hasConflict = DATASET_IMMUTABLE_FIELDS.some(field => (existing[field] ?? null) !== (input[field] ?? null));\n\n    if (hasConflict) {\n      throw new MastraError({\n        id: 'DATASET_ID_CONFLICT',\n        domain: ErrorDomain.STORAGE,\n        category: ErrorCategory.USER,\n        details: {\n          id: input.id,\n          reason: 'IMMUTABLE_FIELDS_MISMATCH',\n        },\n        text: `Dataset ID \"${input.id}\" is already in use with incompatible immutable fields`,\n      });\n    }\n\n    return existing;\n  }\n\n  async dangerouslyClearAll(): Promise<void> {\n    // Default no-op - subclasses override\n  }\n","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/datasets/base.ts#L48-L84","documentation":"When createDataset is called with an id that already exists, resolveExistingDataset compares the stored record's immutable fields against the input (treating omitted and null as equal). Any mismatch throws DATASET_ID_CONFLICT with reason IMMUTABLE_FIELDS_MISMATCH — you cannot reuse an existing dataset id with different immutable configuration.","triggerScenarios":"Calling createDataset with an existing id while changing one of DATASET_IMMUTABLE_FIELDS (e.g. type/format of the dataset, per the immutable-field list) — field values are normalized null-vs-omitted before comparing.","commonSituations":"Re-running seed scripts with changed dataset type, renaming/migrating a dataset definition while keeping the old id, two services defining the same dataset id with different schemas/types.","solutions":["Use a new id for the differently-configured dataset","Keep the immutable fields identical to the existing record if reuse is intended","Delete the existing dataset first, then re-create with new fields","Read details.reason/details in the MastraError to identify the exact mismatched field"],"exampleFix":"// before\nawait storage.createDataset({ id: 'events', type: 'jsonl', ... }) // existing is type 'csv'\n// after\nawait storage.createDataset({ id: 'events-v2', type: 'jsonl', ... })","handlingStrategy":"try-catch","validationCode":"const existing = await storage.getDatasetById({ id });\nif (existing && DATASET_IMMUTABLE_FIELDS.some(f => (existing[f] ?? null) !== (input[f] ?? null))) {\n  throw new Error(`id ${id} in use with different immutable fields`);\n}","typeGuard":"null","tryCatchPattern":"try {\n  await storage.createDataset(input);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'DATASET_ID_CONFLICT') {\n    // use a new id or align immutable fields\n  }\n  throw e;\n}","preventionTips":["Keep dataset definitions (immutable fields) in one canonical place","Version ids in the name (events-v2) when config changes","Check existing dataset before create in seed scripts","Don't let two services define the same dataset id differently"],"tags":["storage","datasets","conflict","immutability"],"backgroundTag":"duplicate-resource-id","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}