mastra-ai/mastra · error · MastraError

DATASET_ID_CONFLICT

DATASET_ID_CONFLICT

Error message

Dataset ID "${input.id}" is already in use with incompatible immutable fields

What it means

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.

Source

Thrown at packages/core/src/storage/domains/datasets/base.ts:66

      throw new MastraError({
        id: 'DATASET_INVALID_ID',
        domain: ErrorDomain.STORAGE,
        category: ErrorCategory.USER,
        details: { id },
        text: 'Caller-defined dataset ID must not be empty',
      });
    }
  }

  /**
   * Returns an existing dataset when a caller-defined ID is reused compatibly.
   * Optional immutable fields normalize omitted and null values to the same value.
   */
  protected resolveExistingDataset(existing: DatasetRecord, input: CreateDatasetInput & { id: string }): DatasetRecord {
    const hasConflict = DATASET_IMMUTABLE_FIELDS.some(field => (existing[field] ?? null) !== (input[field] ?? null));

    if (hasConflict) {
      throw new MastraError({
        id: 'DATASET_ID_CONFLICT',
        domain: ErrorDomain.STORAGE,
        category: ErrorCategory.USER,
        details: {
          id: input.id,
          reason: 'IMMUTABLE_FIELDS_MISMATCH',
        },
        text: `Dataset ID "${input.id}" is already in use with incompatible immutable fields`,
      });
    }

    return existing;
  }

  async dangerouslyClearAll(): Promise<void> {
    // Default no-op - subclasses override
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a new id for the differently-configured dataset
2. Keep the immutable fields identical to the existing record if reuse is intended
3. Delete the existing dataset first, then re-create with new fields
4. Read details.reason/details in the MastraError to identify the exact mismatched field

Example fix

// before
await storage.createDataset({ id: 'events', type: 'jsonl', ... }) // existing is type 'csv'
// after
await storage.createDataset({ id: 'events-v2', type: 'jsonl', ... })

const existing = await storage.getDatasetById({ id });
if (existing && DATASET_IMMUTABLE_FIELDS.some(f => (existing[f] ?? null) !== (input[f] ?? null))) {
  throw new Error(`id ${id} in use with different immutable fields`);
}

null

try {
  await storage.createDataset(input);
} catch (e) {
  if (e instanceof MastraError && e.id === 'DATASET_ID_CONFLICT') {
    // use a new id or align immutable fields
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• DATASETS_STORAGE_NOT_CONFIGURED
• DATASETS_STORE_NOT_AVAILABLE
• DATASET_NOT_FOUND
• EXPERIMENT_ID_CONFLICT
• DATASETS_STORAGE_NOT_CONFIGURED

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