What causes "invalid metadata field key: %w" in gastownhall/beads?

Fix the first key named by the error (keys are checked alphabetically, so fix-and-rerun iterates through remaining offenders)

gastownhall/beads · error

invalid metadata field key: %w

Error message

invalid metadata field key: %w

What it means

ValidateMetadataFilters checks each key of the fields map (in sorted order, so repeated runs name the same first offender) with storage.ValidateMetadataKey and wraps any failure as 'invalid metadata field key'. It exists so field-equality filters get the same key rules as --has-key, with deterministic error output. The inner error carries the concrete violation.

Source

Thrown at internal/workapi/metadata.go:38

// it in its own words: this is the floor under every caller, not a replacement
// for a front door's usage error.
//
// Keys are checked in sorted order so a request with two bad keys always names
// the same one.
func ValidateMetadataFilters(fields map[string]string, hasKey string) error {
	if hasKey != "" {
		if err := storage.ValidateMetadataKey(hasKey); err != nil {
			return fmt.Errorf("invalid metadata key filter: %w", err)
		}
	}
	keys := make([]string, 0, len(fields))
	for k := range fields {
		keys = append(keys, k)
	}
	sort.Strings(keys)
	for _, k := range keys {
		if err := storage.ValidateMetadataKey(k); err != nil {
			return fmt.Errorf("invalid metadata field key: %w", err)
		}
	}
	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

Fix the first key named by the error (keys are checked alphabetically, so fix-and-rerun iterates through remaining offenders)
Conform keys to ValidateMetadataKey's rules: allowed charset, length, non-empty
Compare against keys present on real issues (`bd show <id>`) to confirm exact spelling

Example fix

// before
fields := map[string]string{"review.status": "approved"}
// after
fields := map[string]string{"review-status": "approved"}

Defensive patterns

Strategy: validation

Validate before calling

for k := range fields {
	if err := storage.ValidateMetadataKey(k); err != nil {
		return fmt.Errorf("field %q: %w", k, err)
	}
}

Try / catch

err := ValidateMetadataFilters(fields, hasKey)
if err != nil && strings.HasPrefix(err.Error(), "invalid metadata field key") {
	return fmt.Errorf("fix metadata field filters: %w", err)
}

Prevention

Validate every field-map key with storage.ValidateMetadataKey before building filters
Generate keys from a shared constant set, not free-form config
Re-check filters after any upstream key rename

When it happens

Trigger: Calling BuildListFilter or BuildReadyFilter where any key in the fields map fails ValidateMetadataKey — bad characters, wrong length, or empty string after trimming.

Common situations: Passing metadata filters from a config file where keys were authored free-form; upstream tooling emitting keys with dots or slashes; a key renamed at the source while an old filter still references the old spelling.

Related errors

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