{"record":{"id":"f6813b0a73d914b0","repo":"mastra-ai/mastra","slug":"schemaupdatevalidationerror","errorCode":null,"errorMessage":"SchemaUpdateValidationError","messagePattern":"SchemaUpdateValidationError","errorType":"exception","errorClass":"SchemaUpdateValidationError","httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/datasets/base.ts","lineNumber":140,"sourceCode":"      });\n      const items = itemsResult.items;\n\n      if (items.length > 0) {\n        const validator = getSchemaValidator();\n        const newInputSchema = args.inputSchema !== undefined ? args.inputSchema : existing.inputSchema;\n        const newOutputSchema =\n          args.groundTruthSchema !== undefined ? args.groundTruthSchema : existing.groundTruthSchema;\n\n        const result = validator.validateBatch(\n          items.map(i => ({ input: i.input, groundTruth: i.groundTruth })),\n          newInputSchema,\n          newOutputSchema,\n          `dataset:${args.id}:schema-update`,\n          10, // Max 10 errors to report\n        );\n\n        if (result.invalid.length > 0) {\n          throw new SchemaUpdateValidationError(result.invalid);\n        }\n\n        // Clear old cache since schema changed\n        validator.clearCache(`dataset:${args.id}:input`);\n        validator.clearCache(`dataset:${args.id}:output`);\n      }\n    }\n\n    return this._doUpdateDataset(args);\n  }\n\n  /** Subclasses implement actual storage update logic */\n  protected abstract _doUpdateDataset(args: UpdateDatasetInput): Promise<DatasetRecord>;\n\n  /**\n   * Add an item to a dataset. Validates input/groundTruth against dataset schemas.\n   * Subclasses implement _doAddItem which handles SCD-2 versioning internally.\n   */","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/datasets/base.ts#L122-L158","documentation":"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.","triggerScenarios":"Calling updateDataset with a new inputSchema/outputSchema while stored items violate the new schema (missing required fields, wrong types, failed constraints).","commonSituations":"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.","solutions":["Read result.invalid items from the error and fix/migrate those items to match the new schema first","Loosen the new schema (optional fields, unions) to accept existing items","Delete or archive non-conforming items before updating the schema","Validate the new schema against current items yourself before calling updateDataset"],"exampleFix":"// before\nawait storage.updateDataset({ id: 'ds', inputSchema: { required: ['email'] } }) // old items lack email\n// after\nawait storage.updateDataset({ id: 'ds', inputSchema: { required: [], properties: { email: { type: 'string' } } } })\n// then backfill items and tighten the schema later","handlingStrategy":"try-catch","validationCode":"import { validateItemsAgainstSchemas } from '@mastra/core';\nconst result = validateItemsAgainstSchemas(existingItems, newInputSchema, newOutputSchema, `dataset:${id}:precheck`, 10);\nif (result.invalid.length > 0) throw new Error('existing items violate new schema');","typeGuard":"null","tryCatchPattern":"try {\n  await storage.updateDataset(args);\n} catch (e) {\n  if (e.name === 'SchemaUpdateValidationError') {\n    const badItems = e.invalid; // fix/migrate these before retrying\n  }\n  throw e;\n}","preventionTips":["Backfill/migrate items before tightening schemas","Prefer additive schema changes (new optional fields)","Run schema validation against current items in CI","Version the dataset (new id) for breaking schema changes"],"tags":["storage","datasets","schema","validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}