gastownhall/beads · error · storage.ErrPrefixMismatch

%w: issue ID %s does not match configured prefix %s

Error message

%w: issue ID %s does not match configured prefix %s

What it means

Returned (wrapping storage.ErrPrefixMismatch) when validating that a given issue ID starts with one of the configured allowed ID prefixes. Each prefix must appear as '<prefix>-' at the start of the ID. This enforces organization-wide ID naming configured via the prefix setting.

Source

Thrown at internal/storage/domain/issue.go:1072

			return result, fmt.Errorf("create: add waits-for: %w", err)
		}
		result.PostCreateWrites = true
	}

	return result, nil
}

func validateExplicitIDPrefix(id, prefix, allowedPrefixes string) error {
	if strings.HasPrefix(id, prefix+"-") {
		return nil
	}
	for _, allowed := range strings.Split(allowedPrefixes, ",") {
		allowed = strings.TrimSpace(allowed)
		if allowed != "" && strings.HasPrefix(id, allowed+"-") {
			return nil
		}
	}
	return fmt.Errorf("%w: issue ID %s does not match configured prefix %s", storage.ErrPrefixMismatch, id, prefix)
}

func (u *issueUseCaseImpl) CreateIssues(ctx context.Context, params []CreateIssueParams, actor string) (CreateIssuesResult, error) {
	return u.createMany(ctx, params, actor, false)
}

func (u *issueUseCaseImpl) CreateWisps(ctx context.Context, params []CreateIssueParams, actor string) (CreateIssuesResult, error) {
	return u.createMany(ctx, params, actor, true)
}

func (u *issueUseCaseImpl) createMany(ctx context.Context, params []CreateIssueParams, actor string, useWisp bool) (CreateIssuesResult, error) {
	result := CreateIssuesResult{}
	for i := range params {
		r, err := u.create(ctx, params[i], actor, useWisp)
		if err != nil {
			return result, fmt.Errorf("createMany[%d]: %w", i, err)
		}
		result.Issues = append(result.Issues, r.Issue)

View on GitHub (pinned to 71377f2769)

Solutions

1. Update the configured prefix (or comma-separated allowed prefixes) to include the ID's actual prefix
2. Re-prefix the issue ID to match configuration (create anew with the correct prefix)
3. If migrating prefixes, bulk-update IDs or accept/re-map imports before validation
4. Check for whitespace/typo in the prefix config

Example fix

// before: config prefix 'bd' but ID from another repo
issueID := "proj-42"
// after: align config to allow both, or remap the ID
allowedPrefixes = "bd,proj"
// or
issueID = "bd-42"

func validPrefix(id, prefix string) bool {
    for _, p := range strings.Split(prefix, ",") {
        p = strings.TrimSpace(p)
        if p != "" && strings.HasPrefix(id, p+"-") {
            return true
        }
    }
    return false
}
// call before importing: if !validPrefix(issueID, cfg.Prefix) { remap(issueID) }

if err := importIssues(ctx, issues); err != nil {
    if errors.Is(err, storage.ErrPrefixMismatch) {
        // remap IDs to the configured prefix and retry
    }
}

When it happens

Trigger: Calling an update/import/validation path with an issue ID whose prefix does not match the configured prefix (e.g. ID 'proj-123' when prefix is 'bd', or prefix list doesn't include the ID's prefix).

Common situations: Changing the configured prefix after issues were created with an older prefix; importing issues from another repo/workspace with different prefixes; typo'd or copied IDs from another project; multiple prefixes configured but the CSV list missing one.

Related errors

• %q is set by bd init --prefix, bd bootstrap or bd rename-pre
• server: NewDoltServer: doltBinExec is required
• server: NewDoltServer: rootDir is required
• server: NewDoltServer: configPath is required
• ErrPrefixMismatch

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