What causes "invalid issue type: %s" in gastownhall/beads?

Use one of the canonical types: bug, feature, task, epic, chore

invalid issue type: %s

Error message

invalid issue type: %s

What it means

ParseIssueType validates a user-supplied issue type string and returns this error when, after trimming whitespace and normalizing aliases (e.g. "enhancement" -> "feature"), the value is not one of the canonical types recognized by types.IssueType.IsValid(). The library supports a fixed set of types (bug, feature, task, epic, chore); anything else is rejected.

Source

Thrown at internal/validation/bead.go:38

	}

	var p int
	if _, err := fmt.Sscanf(content, "%d", &p); err == nil && p >= 0 && p <= 4 {
		return p
	}
	return -1 // Invalid
}

// ParseIssueType extracts and validates an issue type from content.
// Returns the validated type or error if invalid.
// Supports type aliases like "enhancement" -> "feature".
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)

View on GitHub (pinned to 71377f2769)

Solutions

Use one of the canonical types: bug, feature, task, epic, chore
Use the alias "enhancement" (normalized to feature) if that is the intent
Upgrade beads if relying on aliases not present in your installed version
Normalize/whitelist types in your import script before calling ParseIssueType

Example fix

// before
t, err := validation.ParseIssueType("bugfix") // invalid
// after
t, err := validation.ParseIssueType("bug") // canonical type (or "enhancement" -> feature)

Defensive patterns

Strategy: validation

Validate before calling

var validTypes = map[string]bool{"bug":true,"feature":true,"task":true,"epic":true,"chore":true,"enhancement":true}
func validType(s string) bool { return validTypes[strings.ToLower(strings.TrimSpace(s))] }

Try / catch

t, err := validation.ParseIssueType(content)
if err != nil {
    return fmt.Errorf("%w (allowed: bug, feature, task, epic, chore)", err)
}

Prevention

Whitelist types in import scripts before calling ParseIssueType
Normalize casing and trim whitespace on user input
Map foreign tracker types (story->feature, enhancement->feature) up front
Keep beads updated so alias normalization matches docs

When it happens

Trigger: Calling validation.ParseIssueType with a string not in the canonical set or its aliases — e.g. "story", "spike", "Feature Request", "bugfix", or an empty-after-trim string. The error reports the original (un-normalized) content.

Common situations: Typing "enhancement" in an old version without the alias; scripts exporting types from another tracker (Jira "story", GitHub "enhancement" on old beads); non-English type names; accidental capitalization plus unrecognized word like "BUGFIX" in older builds lacking case normalization.

Related errors

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