gastownhall/beads · error

spec only supports = operator

Error message

spec only supports = operator

What it means

Thrown when the `spec` field is compared with an operator other than `=`. Spec filtering supports only equality, including a trailing-`*` prefix form (which maps to SpecIDPrefix).

Source

Thrown at internal/query/evaluator.go:442

	return nil
}

func (e *Evaluator) applyIDFilter(comp *ComparisonNode, filter *types.IssueFilter) error {
	if comp.Op != OpEquals {
		return fmt.Errorf("id only supports = operator")
	}
	// Check if it looks like a prefix (ends with *)
	if strings.HasSuffix(comp.Value, "*") {
		filter.IDPrefix = strings.TrimSuffix(comp.Value, "*")
	} else {
		filter.IDs = append(filter.IDs, comp.Value)
	}
	return nil
}

func (e *Evaluator) applySpecFilter(comp *ComparisonNode, filter *types.IssueFilter) error {
	if comp.Op != OpEquals {
		return fmt.Errorf("spec only supports = operator")
	}
	// Support prefix matching
	if strings.HasSuffix(comp.Value, "*") {
		filter.SpecIDPrefix = strings.TrimSuffix(comp.Value, "*")
	} else {
		filter.SpecIDPrefix = comp.Value
	}
	return nil
}

func (e *Evaluator) applyParentFilter(comp *ComparisonNode, filter *types.IssueFilter) error {
	if comp.Op != OpEquals {
		return fmt.Errorf("parent only supports = operator")
	}
	filter.ParentID = &comp.Value
	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

  1. Use `spec = <spec-id>` or `spec = <prefix>*` for prefix matching.
  2. For fuzzy/substring search, use the text-search field instead of `spec`.
  3. Validate the query with the parser before scripting it.

Example fix

// before
bd list 'spec ~ auth*'
// after
bd list 'spec = auth*'
Defensive patterns

Strategy: validation

Validate before calling

func validateSpecComparison(op string) error {
	if op != "=" {
		return fmt.Errorf("spec supports only = (with optional trailing *), got %q", op)
	}
	return nil
}

Prevention

When it happens

Trigger: Queries like `spec != BD-100`, `spec > foo`, or `spec ~ foo*` reaching applySpecFilter.

Common situations: Trying substring/regex matching with `~`; assuming spec behaves like free-text search; typos in saved queries after renaming fields.

Related errors

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