gastownhall/beads · error · ErrValidation

%w: --ready cannot filter on %s; the blocker-aware ready que

Error message

%w: --ready cannot filter on %s; the blocker-aware ready query carries only part of the list vocabulary, so answering would return every ready issue rather than the ones asked for — drop --ready, or drop what it cannot carry

What it means

ValidateReadyFlagScope rejects --ready queries combined with list filters the blocker-aware ready query cannot honor. The ready query implements only a subset of the full list filter vocabulary; honoring an unsupported filter would silently return every ready issue instead of the requested subset, so the validator fails fast naming the offending filters.

Source

Thrown at issueops/reader_ready_scope.go:128

// backend can be missing it — a per-backend copy is the drift this role exists
// to remove.
//
// A request without ReadyFlag is never refused here: every field below is
// honored by the ordinary listing.
func ValidateReadyFlagScope(req ListRequest) error {
	if !req.ReadyFlag {
		return nil
	}
	var named []string
	for _, f := range readyScopeFields {
		if f.set(req) {
			named = append(named, f.name+" ("+f.flag+")")
		}
	}
	if len(named) == 0 {
		return nil
	}
	return fmt.Errorf("%w: --ready cannot filter on %s; the blocker-aware ready query carries only part of the list vocabulary, so answering would return every ready issue rather than the ones asked for — drop --ready, or drop what it cannot carry",
		ErrValidation, strings.Join(named, ", "))
}

View on GitHub (pinned to 71377f2769)

Solutions

Remove the unsupported filter flags named in the message from the --ready query.
Post-filter the ready results yourself (e.g. pipe through `bd list` or filter by label client-side).
If filtering is essential, use the full list query instead of --ready and apply readiness criteria manually.

Example fix

// before
bd ready --ready --label backend

// after
bd ready
# then filter labeled issues from the output, or use the list query with readiness criteria

Defensive patterns

Strategy: validation

Validate before calling

// validate flags before invoking the ready query
unsupported := []string{"--label", "--assignee"} // flags outside ready vocabulary
for _, f := range args {
	if slices.Contains(unsupported, f) {
		return fmt.Errorf("%s is not supported with --ready", f)
	}
}

Try / catch

if err := run(); err != nil {
	if strings.Contains(err.Error(), "--ready cannot filter on") {
		// strip unsupported filters and retry plain `bd ready`
	}
	return err
}

Prevention

Do not mix `bd list` filter flags into `bd ready` invocations.
Check `bd ready --help` for the supported flag set before scripting.
Post-filter ready output client-side when extra criteria are needed.

When it happens

Trigger: Running `bd ready --ready --label foo` (or any --assignee/--status-type style filter) where the flag is in the unsupported set accumulated into `named`; any programmatic query that combines ReadyFilter with list-only filters.

Common situations: Scripts that append standard list flags to a ready query; users familiar with `bd list` flag surface applying it to `bd ready`; automation built before the ready-query filter scope was narrowed.

Related errors

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