gastownhall/beads · error

uow: database %q is at schema v%d, this bd expects v%d; the

Error message

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

What it means

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.

Source

Thrown at internal/storage/uow/team_server_schema.go:30

// matches this binary's. The connection must already have the database selected.
func checkTeamServerSchema(ctx context.Context, conn schema.DBConn, database string) error {
	current, err := schema.CurrentVersion(ctx, conn)
	if err != nil {
		return fmt.Errorf("uow: team-server schema check: %w", err)
	}
	latest := schema.LatestVersion()
	switch {
	case current == 0:
		return fmt.Errorf(
			"uow: database %q has no beads schema — the schema is managed by beads-team-server; ask your operator to run 'bts init' first",
			database)
	case current > latest:
		return schema.CheckForwardDrift(ctx, conn)
	case current < latest:
		// No BD_IGNORE_SCHEMA_SKEW hatch here: it would let a newer bd write
		// against an older bts schema. Not SchemaBehindError either: its "run
		// any bd write command to migrate" advice is wrong for a bts-owned schema.
		return fmt.Errorf(
			"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",
			database, current, latest, current)
	}
	return nil
}

// checkTeamServerIdentity verifies that the bts-managed database this
// invocation is about to open really belongs to the calling workspace's
// project. The connection must already have the database selected.
//
// The proxied/team-server path never constructs a DoltStore, so
// DoltStore.verifyProjectIdentity — which guards every non-CreateIfMissing
// gateway open — is unreachable here. `bd init --team-server` ADOPTS whatever
// identity the shared database carries (it has no expected value to assert
// against), and before this check nothing re-asserted it on any later open.
// That was tolerable while proxied-server meant a per-workspace database bd
// created itself; --team-server points bd at a long-lived operator-managed
// database selectable per invocation via --database, which is exactly the

View on GitHub (pinned to 71377f2769)

Solutions

1. Ask the operator to run 'bts migrate' to bring the database to the latest schema version
2. Use a bd binary built against the database's current schema version (downgrade or version-pin the client)
3. Keep client and server versions in lockstep when upgrading

Example fix

// before
bd sync  # database at v12, bd expects v13
// after
bts migrate   # operator migrates schema to v13
bd sync

-- preflight: compare schema versions before connecting
SELECT value FROM metadata WHERE key='_schema_version';  -- compare to bd's expected version (bd version notes)

func isSchemaBehind(err error) bool {
  return err != nil && strings.Contains(err.Error(), "this bd expects v") && strings.Contains(err.Error(), "bts migrate")
}

err := bdSync(ctx)
if isSchemaBehind(err) {
  // do not retry; operator or client-version action required
  return fmt.Errorf("run 'bts migrate' or use a bd matching the DB schema: %w", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to initialize schema: %w
• checking schema migration work: %w
• counting unbackfilled dependencies.id rows for migration 005
• ignored migrations: %w
• migration %s: %w

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