What causes "id only supports = operator" in gastownhall/beads?

Use `id = ` for exact match or `id = *` for prefix match.

id only supports = operator

Error message

id only supports = operator

What it means

Thrown when the `id` field is used with any operator other than `=`. ID matching only supports equality (with a trailing `*` for prefix matching), so operators like `!=`, `>`, or `~` are rejected.

Source

Thrown at internal/query/evaluator.go:429

	switch comp.Op {
	case OpGreater:
		filter.StartedAfter = &t
	case OpGreaterEq:
		filter.StartedAfter = &t
	case OpLess:
		filter.StartedBefore = &t
	case OpLessEq:
		endOfDay := time.Date(t.Year(), t.Month(), t.Day(), 23, 59, 59, 999999999, t.Location())
		filter.StartedBefore = &endOfDay
	default:
		return fmt.Errorf("started does not support %s operator", comp.Op.String())
	}
	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 {

View on GitHub (pinned to 71377f2769)

Solutions

Use `id = <issue-id>` for exact match or `id = <prefix>*` for prefix match.
To exclude an ID, combine with `not` at the query level if supported, or filter results client-side.
Drop regex/comparison operators; IDs support only equality semantics.

Example fix

// before
bd list 'id ~ bd-12*'
// after
bd list 'id = bd-12*'

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Use `id = <id>` or `id = <prefix>*` only.
Handle exclusions at the query/result level, not with != on id.
Do not attempt regex operators on ID fields.

When it happens

Trigger: Queries like `id != bd-123`, `id > bd-100`, or `id ~ bd-1*` reaching applyIDFilter.

Common situations: Users attempting exclusion queries with `!=` and not knowing the negation must be expressed differently; guessing regex-ish operators; old SQL habits.

Related errors

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