{"record":{"id":"755514a40825a4ad","repo":"gastownhall/beads","slug":"uow-database-q-is-at-schema-v-d-this-bd-expects","errorCode":null,"errorMessage":"uow: database %q is at schema v%d, this bd expects v%d; the schema is managed by beads-team-server — ask your operator to run 'bts migrate', or use a bd built against schema v%d","messagePattern":"uow: database %q is at schema v(.+?), this bd expects v(.+?); the schema is managed by beads-team-server — ask your operator to run 'bts migrate', or use a bd built against schema v(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/uow/team_server_schema.go","lineNumber":30,"sourceCode":"// matches this binary's. The connection must already have the database selected.\nfunc checkTeamServerSchema(ctx context.Context, conn schema.DBConn, database string) error {\n\tcurrent, err := schema.CurrentVersion(ctx, conn)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"uow: team-server schema check: %w\", err)\n\t}\n\tlatest := schema.LatestVersion()\n\tswitch {\n\tcase current == 0:\n\t\treturn fmt.Errorf(\n\t\t\t\"uow: database %q has no beads schema — the schema is managed by beads-team-server; ask your operator to run 'bts init' first\",\n\t\t\tdatabase)\n\tcase current > latest:\n\t\treturn schema.CheckForwardDrift(ctx, conn)\n\tcase current < latest:\n\t\t// No BD_IGNORE_SCHEMA_SKEW hatch here: it would let a newer bd write\n\t\t// against an older bts schema. Not SchemaBehindError either: its \"run\n\t\t// any bd write command to migrate\" advice is wrong for a bts-owned schema.\n\t\treturn fmt.Errorf(\n\t\t\t\"uow: database %q is at schema v%d, this bd expects v%d; the schema is managed by beads-team-server — ask your operator to run 'bts migrate', or use a bd built against schema v%d\",\n\t\t\tdatabase, current, latest, current)\n\t}\n\treturn nil\n}\n\n// checkTeamServerIdentity verifies that the bts-managed database this\n// invocation is about to open really belongs to the calling workspace's\n// project. The connection must already have the database selected.\n//\n// The proxied/team-server path never constructs a DoltStore, so\n// DoltStore.verifyProjectIdentity — which guards every non-CreateIfMissing\n// gateway open — is unreachable here. `bd init --team-server` ADOPTS whatever\n// identity the shared database carries (it has no expected value to assert\n// against), and before this check nothing re-asserted it on any later open.\n// That was tolerable while proxied-server meant a per-workspace database bd\n// created itself; --team-server points bd at a long-lived operator-managed\n// database selectable per invocation via --database, which is exactly the","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/team_server_schema.go#L12-L48","documentation":"checkTeamServerSchema refuses to run bd when the database's schema version is OLDER than the version this bd binary expects. Because the schema is owned by beads-team-server, bd deliberately does not offer a self-migration hatch; the database must be migrated by 'bts migrate' or the client must use a bd built for the database's schema version.","triggerScenarios":"Connecting to a bts-owned database whose stored schema version (current) is less than schema.LatestVersion() of the running bd binary — i.e. server not yet migrated while client was upgraded.","commonSituations":"Operator upgraded bd clients before running 'bts migrate' on the server; mixed-version fleet where one developer installed a newer bd; rollback of the server without downgrading clients.","solutions":["Ask the operator to run 'bts migrate' to bring the database to the latest schema version","Use a bd binary built against the database's current schema version (downgrade or version-pin the client)","Keep client and server versions in lockstep when upgrading"],"exampleFix":"// before\nbd sync  # database at v12, bd expects v13\n// after\nbts migrate   # operator migrates schema to v13\nbd sync","handlingStrategy":"validation","validationCode":"-- preflight: compare schema versions before connecting\nSELECT value FROM metadata WHERE key='_schema_version';  -- compare to bd's expected version (bd version notes)","typeGuard":"func isSchemaBehind(err error) bool {\n  return err != nil && strings.Contains(err.Error(), \"this bd expects v\") && strings.Contains(err.Error(), \"bts migrate\")\n}","tryCatchPattern":"err := bdSync(ctx)\nif isSchemaBehind(err) {\n  // do not retry; operator or client-version action required\n  return fmt.Errorf(\"run 'bts migrate' or use a bd matching the DB schema: %w\", err)\n}","preventionTips":["Run 'bts migrate' before rolling out newer bd binaries to the team","Keep client bd versions and server schema version in lockstep","Check bd release notes for schema version bumps before upgrading","Avoid mixing bd versions across a team against one bts database"],"tags":["database","schema","version-mismatch","team-server","migration"],"backgroundTag":"schema-version-mismatch","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}