invalid priority %q (expected 0-4 or P0-P4, not words like h

Error message

invalid priority %q (expected 0-4 or P0-P4, not words like high/medium/low)

What it means

ValidatePriority parses a priority string supporting numeric 0-4 and P-prefixed P0-P4 forms. It returns this error when ParsePriority yields -1, i.e. the string is not a number in range after optional P-prefix stripping — most commonly because word forms like "high"/"medium"/"low" were used, which the parser deliberately does not accept.

Source

Thrown at internal/validation/bead.go:50

func ParseIssueType(content string) (types.IssueType, error) {
	// Normalize to support aliases like "enhancement" -> "feature"
	issueType := types.IssueType(strings.TrimSpace(content)).Normalize()

	// Use the canonical IsValid() from types package
	if !issueType.IsValid() {
		return types.TypeTask, fmt.Errorf("invalid issue type: %s", content)
	}

	return issueType, nil
}

// ValidatePriority parses and validates a priority string.
// Returns the parsed priority (0-4) or an error if invalid.
// Supports both numeric (0-4) and P-prefix format (P0-P4).
func ValidatePriority(priorityStr string) (int, error) {
	priority := ParsePriority(priorityStr)
	if priority == -1 {
		return -1, fmt.Errorf("invalid priority %q (expected 0-4 or P0-P4, not words like high/medium/low)", priorityStr)
	}
	return priority, nil
}

// ValidateIDFormat validates that an ID has the correct format.
// Supports: prefix-number (bd-42), prefix-hash (bd-a3f8e9), or hierarchical (bd-a3f8e9.1)
// Also supports hyphenated prefixes like "bead-me-up-3e9" or "web-app-abc123".
// Returns the prefix part or an error if invalid.
func ValidateIDFormat(id string) (string, error) {
	if id == "" {
		return "", nil
	}

	// Must contain hyphen
	if !strings.Contains(id, "-") {
		return "", fmt.Errorf("invalid ID format '%s' (expected format: prefix-hash or prefix-hash.number, e.g., 'bd-a3f8e9' or 'bd-a3f8e9.1')", id)
	}

View on GitHub (pinned to 71377f2769)

Solutions

Convert word priorities to numbers: critical->0/P0, high->1/P1, medium->2/P2, low->3/P3, backlog->4/P4
Pass a plain integer 0-4 or P0-P4 string
Pre-map word values in your import/export script before calling ValidatePriority

Example fix

// before
p, err := validation.ValidatePriority("high") // invalid
// after
p, err := validation.ValidatePriority("P1") // or "1"

Defensive patterns

Strategy: validation

Validate before calling

func validPriority(s string) bool {
    s = strings.TrimSpace(s)
    if len(s) == 2 && strings.EqualFold(s[:1], "P") { s = s[1:] }
    n, err := strconv.Atoi(s)
    return err == nil && n >= 0 && n <= 4
}

Try / catch

p, err := validation.ValidatePriority(raw)
if err != nil {
    return fmt.Errorf("%w; map high/medium/low to 1/2/3 yourself", err)
}

Prevention

Always use numeric or P0-P4 forms in scripts and imports
Maintain a word->number map for migrating from GitHub/Jira labels
Validate priority fields at the boundary of your tooling before calling beads
Remember the range is 0-4 only; values like 5 or P5 are rejected

When it happens

Trigger: Calling validation.ValidatePriority with "high", "low", "critical", "5", "-1", "p9", "", or any non-numeric text. Note the parser strips a leading P/p then requires Sscanf %d with 0<=p<=4, so "P0"-"P4" and "0"-"4" pass; everything else fails.

Common situations: Migrating from trackers that use word priorities (GitHub labels high/medium/low); users typing "high" in a commit message or import file; shell scripts passing "P5" out of habit from other tools; localization producing non-ASCII digits.

Related errors

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