{"record":{"id":"c448568644e9af97","repo":"gastownhall/beads","slug":"metadata-schema-violation-s","errorCode":null,"errorMessage":"metadata schema violation: %s","messagePattern":"metadata schema violation: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/metadata_schema.go","lineNumber":130,"sourceCode":"\tschema := loadMetadataSchema()\n\tif schema.Mode == \"none\" {\n\t\treturn nil\n\t}\n\n\terrs := storage.ValidateMetadataSchema(metadata, schema)\n\tif len(errs) == 0 {\n\t\treturn nil\n\t}\n\n\tif schema.Mode == \"warn\" {\n\t\tfor _, e := range errs {\n\t\t\tfmt.Fprintf(os.Stderr, \"warning: %s\\n\", e.Error())\n\t\t}\n\t\treturn nil\n\t}\n\n\t// mode == \"error\"\n\treturn fmt.Errorf(\"metadata schema violation: %s\", errs[0].Error())\n}\n","sourceCodeStart":112,"sourceCodeEnd":132,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/metadata_schema.go#L112-L132","documentation":"Metadata schema validation ran in \"error\" mode and the issue metadata violated the configured schema. The first violation is reported. Unlike \"warn\" mode (stderr warning), error mode returns a hard failure from validateMetadataIfConfigured.","triggerScenarios":"Calling UpdateIssue (via validateUpdateMetadata) with metadata keys/values that fail the configured metadata schema when BEADS_METADATA_SCHEMA validation mode is set to \"error\".","commonSituations":"Strict CI environments with metadata schema enforcement enabled; custom metadata keys added by scripts/plugins that the schema doesn't declare; typo'd metadata keys; schema tightened after issues were already written with extra metadata.","solutions":["Read the reported violation (errs[0]) and fix the metadata key/value on the update call","Correct the schema configuration if the metadata is legitimate but undeclared","Switch validation mode to \"warn\" if enforcement is too strict for your workflow","Clean existing non-conforming metadata on affected issues before further updates"],"exampleFix":"// before: undeclared metadata key\nbd update bd-42 --metadata '{\"ownr\":\"alice\"}'\n\n// after: declared key\nbd update bd-42 --metadata '{\"owner\":\"alice\"}'","handlingStrategy":"validation","validationCode":"// Validate metadata keys against your schema before updating\nfor key := range metadata {\n    if !schemaAllowsKey(key) {\n        return fmt.Errorf(\"metadata key %q not in schema\", key)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := bd.UpdateIssue(ctx, id, updates); err != nil {\n    if strings.HasPrefix(err.Error(), \"metadata schema violation\") {\n        // fix metadata or relax validation mode\n        return fmt.Errorf(\"metadata rejected: %w\", err)\n    }\n    return err\n}","preventionTips":["Keep metadata keys limited to those declared in your schema config","Lint scripts that write custom metadata","Choose warn vs error mode deliberately per environment"],"tags":["metadata","schema-validation","configuration"],"backgroundTag":"schema-validation-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}