gastownhall/beads · error

uow: database %q has no beads schema — the schema is managed

Error message

uow: database %q has no beads schema — the schema is managed by beads-team-server; ask your operator to run 'bts init' first

What it means

checkTeamServerSchema verifies that the target Dolt database has a beads schema (a nonzero schema version) before bd will operate on it. In team-server mode the schema is owned by beads-team-server, so bd refuses to act on a database with no beads schema and tells the operator to provision it with 'bts init' instead of migrating it itself.

Source

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

import (
	"context"
	"fmt"

	"github.com/steveyegge/beads/internal/storage/issueops"
	"github.com/steveyegge/beads/internal/storage/schema"
)

// checkTeamServerSchema verifies that a bts-managed database's schema version
// 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.

View on GitHub (pinned to 71377f2769)

Solutions

1. Have the operator run 'bts init' on the database to provision the beads schema
2. Verify the --database / dolt_database name in .beads/metadata.json points at the bts-provisioned database
3. Re-run bd init --team-server after the database is provisioned

Example fix

// before
bd sync --database beads_wrong  # uow: database has no beads schema
// after
bts init --database beads   # operator provisions schema
bd sync --database beads

-- preflight: confirm the database was provisioned by bts before running bd
SELECT schema_version FROM information_schema.tables ...  -- or run: bts status --database <name>

func isNoBeadsSchema(err error) bool {
  return err != nil && strings.Contains(err.Error(), "has no beads schema")
}

err := bdSync(ctx)
if isNoBeadsSchema(err) {
  // surface operator action, not a client retry
  return fmt.Errorf("operator must run 'bts init' on the database: %w", err)
}

When it happens

Trigger: Running any bd write/command against a --database that resolves to a Dolt database whose metadata/schema version reads 0 (fresh DB or schema table missing) while verifyTeamServerSchema is active.

Common situations: Typoed or default --database name pointing at an empty database; operator created the database but never ran 'bts init'; the team server was provisioned after clients connected; database was recreated (dropped and re-added) without re-init.

Related errors

• uow: team-server schema check: %w
• uow: database %q is at schema v%d, this bd expects v%d; the
• no database connection
• failed to recompute is_blocked: %w
• no database configuration found

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