What causes "prefix mismatch" in gastownhall/beads?

Omit the explicit ID and let the system allocate one with the configured prefix.

ErrPrefixMismatch

ErrPrefixMismatch

Error message

prefix mismatch

What it means

ErrPrefixMismatch is returned when an issue ID does not match the configured issue prefix (e.g. creating an issue with explicit ID 'abc-1' when the configured prefix is 'bd'). Validated by ValidateIssueIDPrefix and surfaced through create flows (failCreateIssue, ClassifyPublicCreateError).

Source

Thrown at issueops/errors.go:99

// re-exported here. These are ALIASES, so they are the same values: every
// existing issueops.ErrX reference and every errors.Is site keeps matching the
// identical error, and a leaf that never imports issueops still matches it too.
//
// They live down there because none of them names an issue: a request can be
// invalid, a row can be missing and a database can be uninitialized on any
// plane. The refusals BELOW that name issue concepts stay here.
var (
	// ErrNotFound is returned when a requested entity does not exist in the database.
	ErrNotFound = beadserrors.ErrNotFound
	// ErrValidation classifies deterministic request-validation failures.
	ErrValidation = beadserrors.ErrValidation
	// ErrNotInitialized is returned when the database has not been initialized
	// (e.g., issue_prefix config is missing).
	ErrNotInitialized = beadserrors.ErrNotInitialized
)

// ErrPrefixMismatch is returned when an issue ID does not match the configured prefix.
var ErrPrefixMismatch = errors.New("prefix mismatch")

// ErrCloseBlocked is returned by CloseIssueChecked when an issue cannot be
// closed because it is still blocked (is_blocked=1: an open blocking dependency
// or an open blocking gate). Bypass with CloseIssueOptions.Force.
var ErrCloseBlocked = errors.New("cannot close blocked issue")

// ErrCloseOpenChildren is returned when an unforced close finds open
// parent-child dependents.
var ErrCloseOpenChildren = errors.New("cannot close issue with open children")

// CloseOpenChildrenError reports the issue and open-child count that refused a
// guarded close.
type CloseOpenChildrenError struct {
	IssueID      string
	OpenChildren int
}

func (e *CloseOpenChildrenError) Error() string {

View on GitHub (pinned to 71377f2769)

Solutions

Omit the explicit ID and let the system allocate one with the configured prefix.
Change the explicit ID to use the configured prefix (check issue_prefix config).
Fix the issue_prefix config if it is wrong for this workspace.
Run prefix validation (ValidateIssueIDPrefix) before creating to catch it early.

Example fix

// before
bd.Create(types.Issue{ID: "abc-42", Title: "x"}) // prefix mismatch (configured: bd)

// after
bd.Create(types.Issue{Title: "x"}) // ID allocated as bd-N
// or use "bd-42" matching the configured prefix

Defensive patterns

Strategy: validation

Validate before calling

prefix, _ := store.GetConfig(ctx, "issue_prefix")
if !strings.HasPrefix(explicitID, prefix+"-") {
    return fmt.Errorf("ID %s does not use configured prefix %s", explicitID, prefix)
}

Try / catch

if errors.Is(err, issueops.ErrPrefixMismatch) {
    // drop the explicit ID or fix prefix before retrying create
}

Prevention

Let the system allocate IDs instead of passing explicit ones.
Read issue_prefix from config rather than hard-coding.
Validate explicit IDs with ValidateIssueIDPrefix before create.

When it happens

Trigger: Creating an issue with an explicit ID whose prefix differs from the configured issue_prefix config; useCaseExplicitIDPrefixGuard rejecting explicit IDs; copying IDs from another beads repository/workspace with a different prefix.

Common situations: Clone/fork of a repo with a different configured prefix; scripts hard-coding IDs from another project; issue_prefix config missing or changed after migration (related: ErrNotInitialized when config absent).

Related errors

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