gastownhall/beads · error

invalid status %q in multi-status filter (valid: %s)

Error message

invalid status %q in multi-status filter (valid: %s)

What it means

applyStatusParts rejects a status token in a multi-status list filter that is not one of the known statuses (open, in_progress, closed, plus any registered custom status names). The library throws this because an unrecognized status would silently produce an empty or meaningless filter. The comma-split values of the --status flag are validated one at a time, and the first invalid token is named verbatim in the error, along with the list of valid values.

Source

Thrown at internal/workapi/list.go:523

	if len(parts) == 1 {
		s := types.Status(parts[0])
		if !s.IsValidWithCustom(customStatusNames) {
			return fmt.Errorf("invalid status %q (valid: %s)", parts[0], ValidStatusList(customStatusNames))
		}
		filter.Status = &s
		return nil
	}

	for _, part := range parts {
		s := types.Status(part)
		if !s.IsValidWithCustom(customStatusNames) {
			// "all" is a real selector on its own (every status), so failing
			// it as merely "invalid" would contradict the flag help. A custom
			// status literally named "all" passes validation above instead.
			if part == "all" {
				return fmt.Errorf(`status "all" cannot be combined with other statuses`)
			}
			return fmt.Errorf("invalid status %q in multi-status filter (valid: %s)", part, ValidStatusList(customStatusNames))
		}
		filter.Statuses = append(filter.Statuses, s)
	}
	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the valid-status list printed in the error (ValidStatusList includes custom status names) and correct the spelling/case of the offending token
2. Run `bd status list` (or inspect configured custom statuses) to confirm the exact names available
3. If the status should exist, register the custom status first, then retry the filter
4. Split a compound --status value to find which single token is invalid

Example fix

// before
bd list --status opne,in_progress
// after
bd list --status open,in_progress

func validStatus(s string, custom map[string]bool) bool {
	switch s {
	case "open", "in_progress", "closed", "all":
		return true
	}
	return custom[s]
}

if err := BuildListFilter(opts); err != nil {
	if strings.HasPrefix(err.Error(), "invalid status") {
		fmt.Fprintf(os.Stderr, "bad --status value; see valid list in message\n")
		os.Exit(2)
	}
	return err
}

When it happens

Trigger: Calling BuildListFilter or ApplyStatusFilter with a status part string that matches no built-in status and no custom status name, e.g. "bd list --status opne" (typo) or "--status Closed" (wrong case).

Common situations: Typos in CLI flags; using a custom status name before it is registered; copying status values from an older version whose set of valid statuses differed; shell scripts hardcoding statuses that a teammate later renamed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• invalid status %q (valid: %s)
• status "all" cannot be combined with other statuses
• invalid metadata key filter: %w
• invalid metadata field key: %w
• got %d close reasons for %d issue IDs; provide exactly one s

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