prefix mismatch: database uses '%s' but you specified '%s' (

Error message

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

What it means

The no-allowed-list variant of the prefix-mismatch family: when no allowed_prefixes are configured and the requested prefix differs from the database prefix (and force is false), validatePrefixWithAllowed returns this simpler message. It guards against creating issues whose IDs would not match the database's namespace.

Source

Thrown at internal/validation/bead.go:123

			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.
func ValidateIDPrefixAllowed(id, dbPrefix, allowedPrefixes string, force bool) error {
	dbPrefix = strings.TrimSuffix(dbPrefix, "-")
	if force || dbPrefix == "" {

View on GitHub (pinned to 71377f2769)

Solutions

Use the database's actual prefix in the ID (shown in the message)
Update your configured prefix if the database prefix is the thing that is wrong (bd config / .beads settings), then retry
Re-run with --force only if intentionally mixing prefixes (e.g. during migration)

Example fix

// before
bd create "Fix login" --id=web-abc123   # db prefix is bd
// after
bd create "Fix login" --id=bd-abc123    # matches database prefix

Defensive patterns

Strategy: validation

Validate before calling

dbPrefix := cfg.Prefix // e.g. from bd config
if dbPrefix != "" && !strings.HasPrefix(id, dbPrefix+"-") {
    return fmt.Errorf("ID %q must use prefix %q", id, dbPrefix)
}

Try / catch

if err := validatePrefix(requested, dbPrefix, false); err != nil {
    if !force {
        return fmt.Errorf("%w — or update your config prefix", err)
    }
    // forced path: log the divergence for audit
    log.Printf("FORCED prefix %q over db %q", requested, dbPrefix)
}

Prevention

After cloning a repo, run `bd doctor` or check config to learn the DB prefix
Read the prefix from config instead of hard-coding "bd" in scripts
When renaming a project, update the prefix in one place and regenerate IDs
Treat --force as a migration tool, not a daily override

When it happens

Trigger: Calling validatePrefix (via issue creation/import validation) where requestedPrefix != dbPrefix, dbPrefix is non-empty, and no allowed list exists — e.g. creating "web-1" in a database configured with prefix "bd".

Common situations: Cloning/forking a project with a different prefix; scripts hard-coding an old prefix after a rename; importing issues exported from another beads database; copying example commands that use a different prefix than your config.

Related errors

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