prefix mismatch: database uses '%s-' but ID '%s' doesn't mat

Error message

prefix mismatch: database uses '%s-' but ID '%s' doesn't match (use --force to override)

What it means

The no-allowed-list variant of ValidateIDPrefixAllowed: when allowed_prefixes is empty and the ID does not start with "<dbPrefix>-", the function returns this message. Only force=true or an empty dbPrefix bypass it. It prevents mixing foreign-prefix issue IDs into a database with a single configured prefix.

Source

Thrown at internal/validation/bead.go:167

	// Check if ID starts with any allowed prefix
	if allowedPrefixes != "" {
		for _, allowed := range strings.Split(allowedPrefixes, ",") {
			allowed = strings.TrimSpace(allowed)
			// Normalize: remove trailing - if present (we add it for matching)
			allowed = strings.TrimSuffix(allowed, "-")
			if allowed != "" && strings.HasPrefix(id, allowed+"-") {
				return nil
			}
		}
	}

	// Build helpful error message
	if allowedPrefixes != "" {
		return fmt.Errorf("prefix mismatch: database uses '%s-' (allowed: %s) but ID '%s' doesn't match any allowed prefix (use --force to override)",
			dbPrefix, allowedPrefixes, id)
	}
	return fmt.Errorf("prefix mismatch: database uses '%s-' but ID '%s' doesn't match (use --force to override)", dbPrefix, id)
}

View on GitHub (pinned to 71377f2769)

Solutions

Rewrite the ID with the database's prefix (shown in the message)
Fix your configured prefix if the DB prefix itself is wrong, then retry
Use --force / force=true only for intentional cross-prefix references (e.g. migration or federation)

Example fix

// before
err := validation.ValidateIDPrefixAllowed("hq-cv-test", "bd", "", false) // mismatch
// after
err := validation.ValidateIDPrefixAllowed("bd-test", "bd", "", false)
// or: validation.ValidateIDPrefixAllowed("hq-cv-test", "bd", "", true) // override

Defensive patterns

Strategy: validation

Validate before calling

if cfg.Prefix != "" && !strings.HasPrefix(id, strings.TrimSuffix(cfg.Prefix, "-")+"-") {
    return fmt.Errorf("ID %q must start with %q-", id, cfg.Prefix)
}

Try / catch

if err := validation.ValidateIDPrefixAllowed(id, dbPrefix, "", false); err != nil {
    if !forceFlag { return err }
    log.Printf("overriding prefix check for %q", id)
    _ = validation.ValidateIDPrefixAllowed(id, dbPrefix, "", true)
}

Prevention

Learn the checkout's prefix (bd config) before generating IDs
Normalize imported IDs to the local prefix on ingest
Never strip or rewrite the prefix when copying IDs between tools
If you genuinely need multiple prefixes, configure allowed_prefixes rather than forcing

When it happens

Trigger: Calling ValidateIDPrefixAllowed with an ID like "hq-cv-test" in a database whose prefix is "bd" with no allowed list configured and force=false. Note the check is on the raw ID string, so even hyphenated prefixes not equal to dbPrefix are rejected here.

Common situations: Refs/issues imported from another beads repo; scripts hard-coding a prefix from a different project; users abbreviating or reformatting IDs (dropping/altering the prefix); config file with the wrong prefix for this checkout.

Related errors

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