invalid ID format '%s' (expected format: prefix-hash or pref

Error message

invalid ID format '%s' (expected format: prefix-hash or prefix-hash.number, e.g., 'bd-a3f8e9' or 'bd-a3f8e9.1')

What it means

ValidateIDFormat checks that an issue ID contains a hyphen so a prefix/hash can be split (it supports hyphenated prefixes like "bead-me-up-3e9" via ExtractIssuePrefix). It returns this error for any non-empty ID with no hyphen at all. Empty strings are allowed and return ("", nil).

Source

Thrown at internal/validation/bead.go:66

	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)
	}

	// Use ExtractIssuePrefix which correctly handles hyphenated prefixes
	// by looking at the last hyphen and checking if suffix is hash-like.
	// This fixes the bug where "bead-me-up-3e9" was parsed as prefix "bead"
	// instead of "bead-me-up".
	prefix := utils.ExtractIssuePrefix(id)

	return prefix, nil
}

// validatePrefix checks that the requested prefix matches the database prefix.
// Returns an error if they don't match (unless force is true).
func validatePrefix(requestedPrefix, dbPrefix string, force bool) error {
	return validatePrefixWithAllowed(requestedPrefix, dbPrefix, "", force)
}

// validatePrefixWithAllowed checks that the requested prefix is allowed.

View on GitHub (pinned to 71377f2769)

Solutions

Include the prefix: use "bd-a3f8e9" instead of "a3f8e9"
For hierarchical IDs use the dotted form "bd-a3f8e9.1"
If you only have a bare hash, prepend your configured prefix (e.g. "bd-" + hash) or resolve it via the partial-ID path which handles normalization
Handle empty input separately — it is valid and returns ("", nil)

Example fix

// before
prefix, err := validation.ValidateIDFormat("a3f8e9") // no hyphen
// after
prefix, err := validation.ValidateIDFormat("bd-a3f8e9") // prefix-hash form

Defensive patterns

Strategy: validation

Validate before calling

func hasIDShape(s string) bool {
    s = strings.TrimSpace(s)
    return s == "" || strings.Contains(s, "-")
}
if !hasIDShape(id) { return fmt.Errorf("%q needs a prefix, e.g. bd-%s", id, id) }

Type guard

func isBareHash(s string) bool {
    return s != "" && !strings.Contains(s, "-")
}

Try / catch

prefix, err := validation.ValidateIDFormat(id)
if err != nil {
    // auto-heal: prepend the configured prefix and retry once
    id = cfg.Prefix + "-" + id
    prefix, err = validation.ValidateIDFormat(id)
}

Prevention

Never pass bare hashes; always carry the "<prefix>-" into ID fields
Sanitize inputs that may be titles or numbers instead of IDs
Handle empty string as a valid no-op case before validation
When accepting user input, offer partial-ID resolution instead of requiring exact format

When it happens

Trigger: Calling validation.ValidateIDFormat with a bare hash ("a3f8e9"), a bare number ("42"), a URL, or any string lacking '-'. The error text is the format guidance shown back to the user.

Common situations: Users typing only the short hash they saw in a listing; scripts stripping the prefix; passing a GitHub issue number like "42"; copy/paste that dropped the "bd-" prefix; accidentally passing a title instead of an ID.

Related errors

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