prefix mismatch: database uses '%s' (allowed: %s) but you sp

Error message

prefix mismatch: database uses '%s' (allowed: %s) but you specified '%s' (use --force to override)

What it means

validatePrefixWithAllowed enforces that the prefix you are creating issues with matches the database's configured prefix (or an entry in the comma-separated allowed_prefixes list, or a prefix of one). When allowedPrefixes is configured and the requested prefix matches none of them, it returns this message telling you the DB prefix, the allowed set, what you specified, and that --force overrides.

Source

Thrown at internal/validation/bead.go:120

	// Check if requestedPrefix is in the allowed list or is a prefix of an allowed entry
	if allowedPrefixes != "" {
		for _, allowed := range strings.Split(allowedPrefixes, ",") {
			allowed = strings.TrimSpace(allowed)
			if allowed == requestedPrefix {
				return nil
			}
			// GH#1135: Also accept if requestedPrefix is a prefix of an allowed entry.
			// This handles IDs like "hq-cv-test" where extraction yields "hq" but
			// the user configured "hq-cv" in allowed_prefixes.
			if strings.HasPrefix(allowed, requestedPrefix+"-") {
				return nil
			}
		}
	}

	// Build helpful error message
	if allowedPrefixes != "" {
		return fmt.Errorf("prefix mismatch: database uses '%s' (allowed: %s) but you specified '%s' (use --force to override)",
			dbPrefix, allowedPrefixes, requestedPrefix)
	}
	return fmt.Errorf("prefix mismatch: database uses '%s' but you specified '%s' (use --force to override)", dbPrefix, requestedPrefix)
}

// ValidateIDPrefixAllowed checks that an issue ID's prefix is allowed.
// Unlike validatePrefixWithAllowed which takes an extracted prefix, this function
// takes the full ID and checks if it starts with any allowed prefix.
// This correctly handles multi-hyphen prefixes like "hq-cv-" where the suffix
// might look like an English word (e.g., "hq-cv-test").
// (GH#1135)
//
// It matches if:
// - force is true
// - dbPrefix is empty
// - id starts with dbPrefix + "-"
// - id starts with any prefix in allowedPrefixes + "-"
// Returns an error if none of these conditions are met.

View on GitHub (pinned to 71377f2769)

Solutions

Use the database's prefix (shown in the error) for new issues
Add your prefix to allowed_prefixes in config if multiple prefixes are legitimate
Re-run with --force if you truly intend a divergent prefix (e.g. migration)
Check for typos and trailing hyphens in the requested prefix vs the allowed list

Example fix

// before
err := validation.ValidateIDPrefixAllowed("web-abc123", "bd", "hq-cv", false) // mismatch
// after
// option 1: use the right prefix
err := validation.ValidateIDPrefixAllowed("hq-cv-abc123", "bd", "hq-cv", false)
// option 2: allow it
// config: allowed_prefixes = "hq-cv,web" or pass force=true

Defensive patterns

Strategy: validation

Validate before calling

requested := utils.ExtractIssuePrefix(id)
allowed := strings.Split(cfg.AllowedPrefixes, ",")
ok := requested == cfg.Prefix
for _, a := range allowed {
    a = strings.TrimSpace(a)
    if requested == a || strings.HasPrefix(a, requested+"-") { ok = true }
}
if !ok { return fmt.Errorf("prefix %q not allowed (db: %s, allowed: %s)", requested, cfg.Prefix, cfg.AllowedPrefixes) }

Try / catch

if err := validation.ValidateIDPrefixAllowed(id, cfg.Prefix, cfg.AllowedPrefixes, false); err != nil {
    if !forceFlag { return err }
    // proceed only with explicit user intent
    _ = validation.ValidateIDPrefixAllowed(id, cfg.Prefix, cfg.AllowedPrefixes, true)
}

Prevention

Check `bd config` / .beads settings for the prefix before creating IDs in a new checkout
Keep allowed_prefixes in sync across team members' clones
Never hard-code a prefix in scripts; read it from config
Avoid --force except for deliberate migrations

When it happens

Trigger: Creating/validating issues where the requested prefix differs from dbPrefix and is neither equal to any allowed_prefixes entry nor a "<requested>-" prefix of one, with force=false. E.g. DB uses "bd", allowed "hq-cv", user requests "web".

Common situations: Cloning a repo whose .beads config uses a different prefix; renaming a project and forgetting to update the prefix config; multi-team setups where each team's prefix must be added to allowed_prefixes; typos in the allowed_prefixes CSV.

Related errors

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