{"record":{"id":"d44304d50ec0f244","repo":"gastownhall/beads","slug":"metadata-schema-violation-s-d44304","errorCode":null,"errorMessage":"metadata schema violation: %s","messagePattern":"metadata schema violation: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/issueops/helpers.go","lineNumber":449,"sourceCode":"\n\tschemaCfg := storage.MetadataSchemaConfig{\n\t\tMode:   mode,\n\t\tFields: fields,\n\t}\n\n\terrs := storage.ValidateMetadataSchema(metadata, schemaCfg)\n\tif len(errs) == 0 {\n\t\treturn nil\n\t}\n\n\tif 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\treturn fmt.Errorf(\"metadata schema violation: %s\", errs[0].Error())\n}\n\n// ParseFieldSchema converts a raw config map into a MetadataFieldSchema.\nfunc ParseFieldSchema(m map[string]interface{}) storage.MetadataFieldSchema {\n\tschema := storage.MetadataFieldSchema{}\n\n\tif t, ok := m[\"type\"].(string); ok {\n\t\tschema.Type = storage.MetadataFieldType(t)\n\t}\n\tif req, ok := m[\"required\"].(bool); ok {\n\t\tschema.Required = req\n\t}\n\n\tif vals, ok := m[\"values\"]; ok {\n\t\tswitch v := vals.(type) {\n\t\tcase []interface{}:\n\t\t\tfor _, item := range v {\n\t\t\t\tif s, ok := item.(string); ok {","sourceCodeStart":431,"sourceCodeEnd":467,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/issueops/helpers.go#L431-L467","documentation":"Issue metadata was rejected by the configured metadata schema. When metadata validation mode is 'enforce' (not 'warn'/'none') and a metadata schema is defined in config, any metadata not conforming (wrong type, missing required field, disallowed enum value, out of min/max range) makes the write fail with the first violation reported.","triggerScenarios":"Calling bd create/update (ApplyMetadataPatch, PrepareIssueForInsert, metadata merge ops) with issue metadata that violates the schema declared under metadata schema fields in config.yaml, while metadata-validation mode is set to enforce/error.","commonSituations":"CI automation writing metadata keys with wrong types (string vs number); a teammate tightened the schema and old scripts now fail; required field added to schema but not supplied; enum value renamed in config but still sent by clients.","solutions":["Fix the metadata payload to satisfy the schema (correct types, include required fields, use allowed values) — the message names the first violation.","If the violation is intentional during migration, set metadata validation mode to 'warn' in config.yaml until callers are updated.","Update the schema in config.yaml if the new metadata shape is the desired contract.","Run validation locally before writing: construct the same schema config and call storage.ValidateMetadataSchema on your metadata JSON to list all violations."],"exampleFix":"// before\nmetadata := map[string]interface{}{\"priority\": \"high\", \"owner\": \"alice\"} // priority must be number, owner required? schema says team required\n// after\nmetadata := map[string]interface{}{\"priority\": 2, \"owner\": \"alice\", \"team\": \"core\"}\nraw, _ := json.Marshal(metadata)\nif err := storage.ValidateMetadataSchema(raw, schemaCfg); len(errs) > 0 { fix(errs) }","handlingStrategy":"validation","validationCode":"func validateBeforeWrite(metadata map[string]interface{}) error {\n    raw, _ := json.Marshal(metadata)\n    fields := loadSchemaFieldsFromConfig() // same source bd reads\n    cfg := storage.MetadataSchemaConfig{Mode: \"error\", Fields: fields}\n    errs := storage.ValidateMetadataSchema(raw, cfg)\n    if len(errs) > 0 { return errors.New(errs[0].Error()) }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if err := storage.ValidateMetadataIfConfigured(rawMeta); err != nil {\n    var retryable bool\n    if strings.HasPrefix(err.Error(), \"metadata schema violation:\") {\n        // fix payload per the reported violation, then retry\n        return fmt.Errorf(\"fix metadata: %w\", err)\n    }\n    return err\n}","preventionTips":["Validate metadata payloads against the schema in CI before bd create/update.","When tightening a schema, first run mode 'warn', migrate all writers, then switch to enforce.","Include all required fields and use schema-declared enum values in automation scripts.","Match JSON types exactly to the schema (numbers as numbers, not strings)."],"tags":["validation","metadata","schema","config"],"backgroundTag":"schema-validation-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}