mastra-ai/mastra · error · SchemaUpdateValidationError

SchemaUpdateValidationError

Error message

SchemaUpdateValidationError

What it means

When updateDataset changes input or output schemas, the new schemas are validated against the dataset's existing items (validateItemsAgainstSchemas, capped at 10 reported errors). If any existing items don't conform, a SchemaUpdateValidationError carrying result.invalid is thrown so the incompatible items can be fixed or the schema adjusted.

Source

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

      });
      const items = itemsResult.items;

      if (items.length > 0) {
        const validator = getSchemaValidator();
        const newInputSchema = args.inputSchema !== undefined ? args.inputSchema : existing.inputSchema;
        const newOutputSchema =
          args.groundTruthSchema !== undefined ? args.groundTruthSchema : existing.groundTruthSchema;

        const result = validator.validateBatch(
          items.map(i => ({ input: i.input, groundTruth: i.groundTruth })),
          newInputSchema,
          newOutputSchema,
          `dataset:${args.id}:schema-update`,
          10, // Max 10 errors to report
        );

        if (result.invalid.length > 0) {
          throw new SchemaUpdateValidationError(result.invalid);
        }

        // Clear old cache since schema changed
        validator.clearCache(`dataset:${args.id}:input`);
        validator.clearCache(`dataset:${args.id}:output`);
      }
    }

    return this._doUpdateDataset(args);
  }

  /** Subclasses implement actual storage update logic */
  protected abstract _doUpdateDataset(args: UpdateDatasetInput): Promise<DatasetRecord>;

  /**
   * Add an item to a dataset. Validates input/groundTruth against dataset schemas.
   * Subclasses implement _doAddItem which handles SCD-2 versioning internally.
   */

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read result.invalid items from the error and fix/migrate those items to match the new schema first
2. Loosen the new schema (optional fields, unions) to accept existing items
3. Delete or archive non-conforming items before updating the schema
4. Validate the new schema against current items yourself before calling updateDataset

Example fix

// before
await storage.updateDataset({ id: 'ds', inputSchema: { required: ['email'] } }) // old items lack email
// after
await storage.updateDataset({ id: 'ds', inputSchema: { required: [], properties: { email: { type: 'string' } } } })
// then backfill items and tighten the schema later

import { validateItemsAgainstSchemas } from '@mastra/core';
const result = validateItemsAgainstSchemas(existingItems, newInputSchema, newOutputSchema, `dataset:${id}:precheck`, 10);
if (result.invalid.length > 0) throw new Error('existing items violate new schema');

null

try {
  await storage.updateDataset(args);
} catch (e) {
  if (e.name === 'SchemaUpdateValidationError') {
    const badItems = e.invalid; // fix/migrate these before retrying
  }
  throw e;
}

When it happens

Trigger: Calling updateDataset with a new inputSchema/outputSchema while stored items violate the new schema (missing required fields, wrong types, failed constraints).

Common situations: Tightening a schema (making a field required, changing a type) on a dataset that already holds legacy items, schema drift between services writing to the same dataset, migrating schemas without cleaning old data.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• COMPARE_INVALID_INPUT
• SchemaValidationError(field, this.formatErrors(result.error)
• DATASET_INVALID_ID
• DATASET_ITEM_EXTERNAL_ID_INVALID
• ${label} contains an unsupported field.

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