What causes "priority must be between 0 and 4" in gastownhall/beads?

Clamp or validate the priority to 0–4 before building the query.

priority must be between 0 and 4

Error message

priority must be between 0 and 4

What it means

Beads supports exactly five priority levels, 0 (critical) through 4 (backlog). applyPriorityFilter rejects any successfully parsed integer outside that range with this error. This keeps query filters aligned with the priority enum used throughout the issue store.

Source

Thrown at internal/query/evaluator.go:231

	status := types.Status(strings.ToLower(comp.Value))
	if !status.IsValid() {
		return fmt.Errorf("invalid status: %s", comp.Value)
	}
	if comp.Op == OpEquals {
		filter.Status = &status
	} else {
		filter.ExcludeStatus = append(filter.ExcludeStatus, status)
	}
	return nil
}

func (e *Evaluator) applyPriorityFilter(comp *ComparisonNode, filter *types.IssueFilter) error {
	priority, err := strconv.Atoi(comp.Value)
	if err != nil {
		return fmt.Errorf("invalid priority value: %s", comp.Value)
	}
	if priority < 0 || priority > 4 {
		return fmt.Errorf("priority must be between 0 and 4")
	}

	switch comp.Op {
	case OpEquals:
		filter.Priority = &priority
	case OpNotEquals:
		// For != we need predicate filtering
		return fmt.Errorf("priority != requires predicate filtering")
	case OpLess:
		// priority < X means PriorityMax = X-1
		max := priority - 1
		if max < 0 {
			return fmt.Errorf("priority < %d matches nothing", priority)
		}
		filter.PriorityMax = &max
	case OpLessEq:
		filter.PriorityMax = &priority
	case OpGreater:

View on GitHub (pinned to 71377f2769)

Solutions

Clamp or validate the priority to 0–4 before building the query.
Map external priority scales into beads' 0–4 range (e.g. Jira P5 → beads 4).
To express "any priority", omit the priority clause entirely rather than using an out-of-range sentinel like 99.

Example fix

// before
"priority <= 9"
// after (beads max is 4)
"priority <= 4"
// Go guard before parsing
if p < 0 || p > 4 { return fmt.Errorf("priority must be 0-4") }

Defensive patterns

Strategy: validation

Validate before calling

func validatePriorityRange(p int) error {
    if p < 0 || p > 4 {
        return fmt.Errorf("priority %d out of range: beads supports 0-4", p)
    }
    return nil
}

Try / catch

if err := e.applyComparison(comp, filter); err != nil {
    if strings.Contains(err.Error(), "priority must be between 0 and 4") {
        p := clamp(comp.Value, 0, 4) // retry with clamped value
        return e.applyPriorityFilter(comp.WithValue(p), filter)
    }
    return err
}

Prevention

Clamp external priority scales into 0-4 before query construction.
Omit the priority clause entirely when "any priority" is meant — never use out-of-range sentinels like 99.
Document beads' 0-4 scale wherever priorities are entered.

When it happens

Trigger: Queries like `priority = 5`, `priority >= 10`, `priority < -1` — any parsed integer < 0 or > 4, regardless of operator.

Common situations: Porting queries from systems with larger priority ranges (Jira 1–5, GitHub labels); scripts that compute priorities arithmetically and overflow; users guessing that P5 or P10 exists.

Related errors

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