gastownhall/beads · error

metadata schema violation: %s

Error message

metadata schema violation: %s

What it means

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.

Source

Thrown at internal/storage/dolt/metadata_schema.go:130

	schema := loadMetadataSchema()
	if schema.Mode == "none" {
		return nil
	}

	errs := storage.ValidateMetadataSchema(metadata, schema)
	if len(errs) == 0 {
		return nil
	}

	if schema.Mode == "warn" {
		for _, e := range errs {
			fmt.Fprintf(os.Stderr, "warning: %s\n", e.Error())
		}
		return nil
	}

	// mode == "error"
	return fmt.Errorf("metadata schema violation: %s", errs[0].Error())
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the reported violation (errs[0]) and fix the metadata key/value on the update call
2. Correct the schema configuration if the metadata is legitimate but undeclared
3. Switch validation mode to "warn" if enforcement is too strict for your workflow
4. Clean existing non-conforming metadata on affected issues before further updates

Example fix

// before: undeclared metadata key
bd update bd-42 --metadata '{"ownr":"alice"}'

// after: declared key
bd update bd-42 --metadata '{"owner":"alice"}'

// Validate metadata keys against your schema before updating
for key := range metadata {
    if !schemaAllowsKey(key) {
        return fmt.Errorf("metadata key %q not in schema", key)
    }
}

if err := bd.UpdateIssue(ctx, id, updates); err != nil {
    if strings.HasPrefix(err.Error(), "metadata schema violation") {
        // fix metadata or relax validation mode
        return fmt.Errorf("metadata rejected: %w", err)
    }
    return err
}

When it happens

Trigger: Calling UpdateIssue (via validateUpdateMetadata) with metadata keys/values that fail the configured metadata schema when BEADS_METADATA_SCHEMA validation mode is set to "error".

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

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

• load %s: %w
• load %s: %w (refusing to fall back to the embedded store)
• loading config for gate resolution: %w
• resolving physical root %s: %w
• configured storage backend %q in metadata.json is not recogn

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/c448568644e9af97. Report an issue: GitHub.