What causes "spec does not support %s operator" in gastownhall/beads?

spec does not support %s operator

Error message

spec does not support %s operator

What it means

The spec field only supports = and != operators. buildSpecPredicate rejects a non-wildcard spec value used with any ordering or other operator, because spec ids are identity strings, not ordered values, in this query language.

Source

Thrown at internal/query/evaluator.go:1020

	hasWildcard := strings.HasSuffix(value, "*")
	if hasWildcard {
		prefix := strings.TrimSuffix(value, "*")
		switch comp.Op {
		case OpEquals:
			return func(i *types.Issue) bool { return strings.HasPrefix(i.SpecID, prefix) }, nil
		case OpNotEquals:
			return func(i *types.Issue) bool { return !strings.HasPrefix(i.SpecID, prefix) }, nil
		default:
			return nil, fmt.Errorf("spec with wildcard only supports = and != operators")
		}
	}
	switch comp.Op {
	case OpEquals:
		return func(i *types.Issue) bool { return i.SpecID == value }, nil
	case OpNotEquals:
		return func(i *types.Issue) bool { return i.SpecID != value }, nil
	default:
		return nil, fmt.Errorf("spec does not support %s operator", comp.Op.String())
	}
}

func (e *Evaluator) buildBoolPredicate(comp *ComparisonNode, getter func(*types.Issue) bool) (func(*types.Issue) bool, error) {
	val := strings.ToLower(comp.Value)
	var boolVal bool
	switch val {
	case "true", "yes", "1":
		boolVal = true
	case "false", "no", "0":
		boolVal = false
	default:
		return nil, fmt.Errorf("invalid boolean value: %s", comp.Value)
	}

	switch comp.Op {
	case OpEquals:
		return func(i *types.Issue) bool { return getter(i) == boolVal }, nil

View on GitHub (pinned to 71377f2769)

Solutions

Use spec = <id> or spec != <id> exactly.
Use a trailing wildcard with = for prefix family matching: spec = auth-*.
OR together multiple exact spec clauses for a set of specs.
Update query-generation code to emit only equality operators for spec fields.

Example fix

// before
bd list --query "spec > bd-100"
// after
bd list --query "spec = bd-100"

Defensive patterns

Strategy: validation

Validate before calling

func checkSpecOperator(op Operator) error {
	if op != OpEquals && op != OpNotEquals {
		return fmt.Errorf("spec supports only = and !=, got %s", op)
	}
	return nil
}

Type guard

func isSpecEqualityQuery(op Operator) bool { return op == OpEquals || op == OpNotEquals }

Try / catch

if err != nil && strings.Contains(err.Error(), "spec does not support") {
	return fmt.Errorf("rewrite spec clause with = or !=: %w", err)
}

Prevention

Never use range operators on spec fields
Use = / != with prefix wildcards for spec families
Port queries from other trackers with operator mapping rules
Add unit tests for query templates covering the spec field

When it happens

Trigger: Queries such as `spec > bd-100` or `spec !=` variants with unsupported operators like contains — any spec comparison whose operator is not = or !=.

Common situations: Users expecting lexicographic spec ranges; query templates shared between numeric and string fields; porting queries from Jira/Lucene-style syntax that allows range operators on keys.

Related errors

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