multiple database files found in %s: %v Please manually rena

Error message

multiple database files found in %s: %v
Please manually rename the correct database to %s and remove others

What it means

When bd init finds more than one non-target, non-backup *.db file in .beads, it cannot tell which legacy database is the real one, so it deliberately fails closed with a message listing the files and asking the user to pick. This is an intentional ambiguity guard, not an I/O failure: renaming the wrong file would silently orphan real issue data.

Source

Thrown at cmd/bd/init.go:2396

	}

	// Filter out the target file name and any backup files
	var oldDBs []string
	for _, match := range matches {
		baseName := filepath.Base(match)
		if baseName != targetName && !strings.HasSuffix(baseName, ".backup.db") {
			oldDBs = append(oldDBs, match)
		}
	}

	if len(oldDBs) == 0 {
		// No old databases to migrate
		return nil
	}

	if len(oldDBs) > 1 {
		// Multiple databases found - ambiguous, require manual intervention
		return fmt.Errorf("multiple database files found in %s: %v\nPlease manually rename the correct database to %s and remove others",
			targetDir, oldDBs, targetName)
	}

	// Migrate the single old database
	oldDB := oldDBs[0]
	if !quiet {
		fmt.Fprintf(os.Stderr, "→ Migrating database: %s → %s\n", filepath.Base(oldDB), targetName)
	}

	// Rename the old database to the new canonical name
	if err := os.Rename(oldDB, targetPath); err != nil {
		return fmt.Errorf("failed to migrate database %s to %s: %w", oldDB, targetPath, err)
	}

	if !quiet {
		fmt.Fprintf(os.Stderr, "✓ Database migration complete\n\n")
	}

View on GitHub (pinned to 71377f2769)

Solutions

List the .beads directory, identify the newest/correct database (check mtimes and contents with a Dolt/SQLite viewer), rename it to beads.db (or the configured target name), and remove or rename the others to *.backup.db.
Move all but the correct file out of .beads temporarily, run bd init to migrate the remaining one, then reconcile extras manually.
If unsure which file is authoritative, use file sizes and modification times, or consult bd issue exports (.beads/issues.jsonl) to match the most recent state.

Example fix

// before
$ ls .beads
issues.db  beads-old.db
$ bd init
# multiple database files found in .beads: [issues.db beads-old.db] ...

// after: pick the correct one, archive the rest
$ mv .beads/beads-old.db .beads/beads-old.backup.db
$ bd init  # migrates issues.db -> beads.db (or rename manually: mv .beads/issues.db .beads/beads.db)

Defensive patterns

Strategy: validation

Validate before calling

// Preflight: detect ambiguous legacy DBs before init
matches, _ := filepath.Glob(filepath.Join(beadsDir, "*.db"))
var ambiguous []string
for _, m := range matches {
    b := filepath.Base(m)
    if b != "beads.db" && !strings.HasSuffix(b, ".backup.db") {
        ambiguous = append(ambiguous, b)
    }
}
if len(ambiguous) > 1 {
    return fmt.Errorf("resolve multiple legacy DBs manually: %v", ambiguous)
}

Try / catch

if err := migrateOldDatabases(targetPath, quiet); err != nil && strings.HasPrefix(err.Error(), "multiple database files found") {
    // prompt the operator to choose the authoritative DB; do not auto-pick
    return err
}

Prevention

Keep exactly one active *.db in .beads; archive old ones as *.backup.db so the migrator ignores them.
After restoring from backups, remove or rename duplicates before running bd init.
Compare file mtimes/sizes to pick the authoritative database when cleaning up.
Never copy a second legacy database into .beads during manual recovery.

When it happens

Trigger: Running `bd init` when migrateOldDatabases finds len(oldDBs) > 1 — i.e. the .beads directory contains two or more *.db files other than the target name and files ending in .backup.db (e.g. beads.db.old plus issues.db).

Common situations: Upgrading a workspace that accumulated multiple legacy database names across bd version changes; copying databases around during a manual recovery; leftover files from interrupted earlier migrations; restoring from backup alongside the original.

Related errors

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