gastownhall/beads · error

clone from %s succeeded, but the database needs %d schema %s

Error message

clone from %s succeeded, but the database needs %d schema %s (v%d -> v%d) that bd will not auto-apply to a remote-backed database (#4259)

What it means

After `bd bootstrap` clones the remote database, a schema-version gate compares the cloned DB's schema version to bd's latest. If pending migrations exist, bd refuses to auto-apply them to a remote-backed database (#4259) and returns this detailed error listing current and target schema versions. The clone succeeded but is unusable until the schema gap is resolved.

Source

Thrown at cmd/bd/bootstrap.go:765

	warmupStore, err := newDoltStoreFromConfig(ctx, plan.BeadsDir)
	if err != nil {
		// #4259: the cloned remote is behind this binary, so the remote-migrate
		// gate held migration for an explicit operator decision. Surface that
		// now with bootstrap-specific guidance and a non-zero exit. Returning
		// silent success here (as this path once did) sent operators in a
		// loop: the first real command failed with the gate message, whose
		// generic "adopt" remedy is `bd bootstrap` — which re-clones the same
		// behind database and silently "succeeds" again (bd-6dnrw.31).
		var gateErr *schema.RemoteMigrateGateError
		if errors.As(err, &gateErr) {
			if !jsonOutput {
				printBootstrapRemoteBehindGuidance(os.Stderr, gateErr, plan.SyncRemote, "bd bootstrap")
			}
			unit := "migrations"
			if gateErr.Pending == 1 {
				unit = "migration"
			}
			return fmt.Errorf("clone from %s succeeded, but the database needs %d schema %s (v%d -> v%d) that bd will not auto-apply to a remote-backed database (#4259)",
				plan.SyncRemote, gateErr.Pending, unit, gateErr.CurrentVersion, gateErr.LatestVersion)
		}
		// Non-fatal: wisp tables will be created on the next command that
		// opens the store. Warn so the user knows to retry if they hit
		// "table not found: wisp_*" errors.
		fmt.Fprintf(os.Stderr, "Warning: post-clone store init failed (wisp tables may be missing): %v\n", err)
		return nil
	}
	configureInitDoltRemote(ctx, warmupStore, plan.SyncRemote, false)
	_ = warmupStore.Close()

	return nil
}

// printBootstrapRemoteBehindGuidance explains a remote-migrate gate refusal in
// bootstrap terms. The gate's generic remedy ("adopt the migrated database:
// bd bootstrap") is wrong from inside a bootstrap-style clone — the database
// was just cloned from the remote, so the REMOTE is what is behind this binary

View on GitHub (pinned to 71377f2769)

Solutions

1. Upgrade bd to the version matching the database schema (`bd --version` vs. the version that wrote the remote), then re-run `bd bootstrap`.
2. If the remote is ahead, run migrations on a non-remote-backed copy or let the newer bd binary that owns those migrations handle the sync.
3. Coordinate team schema versions so all clients use compatible bd releases before syncing.
4. Consult #4259 / the printed guidance (`printBootstrapRemoteBehindGuidance`) for the sanctioned migration path.

Example fix

// before
$ bd bootstrap --remote origin
clone from origin succeeded, but the database needs 2 schema migrations (v12 -> v14)...
// after
$ go install .../bd@latest && bd --version   # ensure binary matches schema v14
$ bd bootstrap --remote origin

# Compare bd version against what wrote the remote before bootstrapping:
bd --version
bd bootstrap --dry-run --remote origin 2>&1 || true
# Parse the reported (vCurrent -> vLatest) gap from the error before deciding to upgrade.

if err := executeSyncAction(ctx, plan, cfg); err != nil {
    var gateErr *SchemaGateError // or match on the (#4259) message
    if strings.Contains(err.Error(), "schema") && strings.Contains(err.Error(), "#4259") {
        // fallback: upgrade the binary to match the remote schema, then retry
        return upgradeBinaryAndRetry(plan)
    }
    return err
}

When it happens

Trigger: `bd bootstrap` with a `--remote` whose database was written by a newer (or older) bd version; the cloned Dolt DB's schema version differs from the binary's, leaving gateErr.Pending migrations unapplied.

Common situations: Upgrading bd on one machine while teammates still push with an older version; pulling a database created by a newer bd release; downgrading bd below the version that created the remote data.

Related errors

• legacy SQLite release marker: %w
• failed to initialize schema: %w
• ignored migrations: %w
• migration %s: %w
• uow: capture fresh database identity: %w

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