{"record":{"id":"c0ef88de164de2ec","repo":"gastownhall/beads","slug":"clone-from-s-succeeded-but-the-database-needs-d","errorCode":null,"errorMessage":"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)","messagePattern":"clone from (.+?) succeeded, but the database needs (.+?) schema (.+?) \\(v(.+?) -> v(.+?)\\) that bd will not auto-apply to a remote-backed database \\(#4259\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/bootstrap.go","lineNumber":765,"sourceCode":"\twarmupStore, err := newDoltStoreFromConfig(ctx, plan.BeadsDir)\n\tif err != nil {\n\t\t// #4259: the cloned remote is behind this binary, so the remote-migrate\n\t\t// gate held migration for an explicit operator decision. Surface that\n\t\t// now with bootstrap-specific guidance and a non-zero exit. Returning\n\t\t// silent success here (as this path once did) sent operators in a\n\t\t// loop: the first real command failed with the gate message, whose\n\t\t// generic \"adopt\" remedy is `bd bootstrap` — which re-clones the same\n\t\t// behind database and silently \"succeeds\" again (bd-6dnrw.31).\n\t\tvar gateErr *schema.RemoteMigrateGateError\n\t\tif errors.As(err, &gateErr) {\n\t\t\tif !jsonOutput {\n\t\t\t\tprintBootstrapRemoteBehindGuidance(os.Stderr, gateErr, plan.SyncRemote, \"bd bootstrap\")\n\t\t\t}\n\t\t\tunit := \"migrations\"\n\t\t\tif gateErr.Pending == 1 {\n\t\t\t\tunit = \"migration\"\n\t\t\t}\n\t\t\treturn 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)\",\n\t\t\t\tplan.SyncRemote, gateErr.Pending, unit, gateErr.CurrentVersion, gateErr.LatestVersion)\n\t\t}\n\t\t// Non-fatal: wisp tables will be created on the next command that\n\t\t// opens the store. Warn so the user knows to retry if they hit\n\t\t// \"table not found: wisp_*\" errors.\n\t\tfmt.Fprintf(os.Stderr, \"Warning: post-clone store init failed (wisp tables may be missing): %v\\n\", err)\n\t\treturn nil\n\t}\n\tconfigureInitDoltRemote(ctx, warmupStore, plan.SyncRemote, false)\n\t_ = warmupStore.Close()\n\n\treturn nil\n}\n\n// printBootstrapRemoteBehindGuidance explains a remote-migrate gate refusal in\n// bootstrap terms. The gate's generic remedy (\"adopt the migrated database:\n// bd bootstrap\") is wrong from inside a bootstrap-style clone — the database\n// was just cloned from the remote, so the REMOTE is what is behind this binary","sourceCodeStart":747,"sourceCodeEnd":783,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/bootstrap.go#L747-L783","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Upgrade bd to the version matching the database schema (`bd --version` vs. the version that wrote the remote), then re-run `bd bootstrap`.","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.","Coordinate team schema versions so all clients use compatible bd releases before syncing.","Consult #4259 / the printed guidance (`printBootstrapRemoteBehindGuidance`) for the sanctioned migration path."],"exampleFix":"// before\n$ bd bootstrap --remote origin\nclone from origin succeeded, but the database needs 2 schema migrations (v12 -> v14)...\n// after\n$ go install .../bd@latest && bd --version   # ensure binary matches schema v14\n$ bd bootstrap --remote origin","handlingStrategy":"fallback","validationCode":"# Compare bd version against what wrote the remote before bootstrapping:\nbd --version\nbd bootstrap --dry-run --remote origin 2>&1 || true\n# Parse the reported (vCurrent -> vLatest) gap from the error before deciding to upgrade.","typeGuard":null,"tryCatchPattern":"if err := executeSyncAction(ctx, plan, cfg); err != nil {\n    var gateErr *SchemaGateError // or match on the (#4259) message\n    if strings.Contains(err.Error(), \"schema\") && strings.Contains(err.Error(), \"#4259\") {\n        // fallback: upgrade the binary to match the remote schema, then retry\n        return upgradeBinaryAndRetry(plan)\n    }\n    return err\n}","preventionTips":["Keep all team members on bd versions that share the same schema version.","Upgrade bd before bootstrapping from a remote last written by a newer release.","Never attempt to hand-migrate a remote-backed database; follow #4259 guidance.","Pin bd versions in CI to avoid mixed-version writers."],"tags":["bootstrap","schema","migration","versioning","dolt"],"backgroundTag":"schema-version-mismatch","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}