What causes "uow: team-server identity check on database %q: %w" in gastownhall/beads?

Retry the command — transient connection/query failures are the most common cause

uow: team-server identity check on database %q: %w

Error message

uow: team-server identity check on database %q: %w

What it means

checkTeamServerIdentity reads the database's stored project identity (metadata._project_id) via GetMetadataInTx and wraps any read failure. At this point the schema check has already proven the metadata table exists, so an error here indicates a real fault querying the shared database, not a legacy-schema situation.

Source

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

//
// expectedProjectID is empty for the paths that legitimately have no
// assertion to make (`bd init`, which adopts, and server-wide database
// maintenance); those skip the check.
func checkTeamServerIdentity(ctx context.Context, conn schema.DBConn, database, expectedProjectID string) error {
	// Soft-skip semantics deliberately mirror DoltStore.verifyProjectIdentity:
	// an empty id on EITHER side means "no assertion available", not
	// "mismatch", so workspaces and databases that predate project identity
	// keep working.
	if expectedProjectID == "" {
		return nil
	}
	// A read error is surfaced rather than skipped: checkTeamServerSchema has
	// already proven the beads schema is present at this binary's version, so
	// the metadata table exists and a failure here is a real fault, not the
	// legacy-database case verifyProjectIdentity tolerates.
	dbProjectID, err := issueops.GetMetadataInTx(ctx, conn, "_project_id")
	if err != nil {
		return fmt.Errorf("uow: team-server identity check on database %q: %w", database, err)
	}
	// Unlike verifyProjectIdentity, an absent stored identity is NOT tolerated
	// here. adoptTeamServerIdentity refuses to attach to a bts database that
	// has no metadata._project_id at all, so for a team-server database this
	// is an already-invalid state rather than a legacy one — and soft-skipping
	// it would mean deleting one row from the shared database silently
	// disables this guard for every client.
	if dbProjectID == "" {
		return fmt.Errorf(
			"uow: database %q has no project identity (metadata._project_id) — the schema is managed by beads-team-server; ask your operator to provision it with 'bts init' (or heal an older bts database with 'bts migrate')",
			database)
	}
	if dbProjectID != expectedProjectID {
		return fmt.Errorf(
			"PROJECT IDENTITY MISMATCH — refusing to connect\n\n"+
				"  Local project ID (metadata.json):  %s\n"+
				"  Database %q project ID:            %s\n\n"+
				"The team server is serving a DIFFERENT project's database.\n"+

View on GitHub (pinned to 71377f2769)

Solutions

Retry the command — transient connection/query failures are the most common cause
Check SQL grants: the bd user must be able to read the metadata table
Verify server health/logs if the error persists
Ensure network stability to the dolt server (timeouts, TLS, proxy)
Check ctx timeouts are not too aggressive for the server round-trip

Example fix

null

Defensive patterns

Strategy: retry

Validate before calling

// Go: verify read access to metadata before the identity check
var v string
err := conn.QueryContext(ctx, "SELECT value FROM metadata WHERE `key` = '_project_id'")

Type guard

func isIdentityReadError(err error) bool {
  return err != nil && strings.Contains(err.Error(), "team-server identity check on database")
}

Try / catch

err := bdSync(ctx)
var netErr net.Error
if isIdentityReadError(err) && (errors.As(err, &netErr) || errors.Is(err, context.DeadlineExceeded)) {
  // transient: retry with backoff
  time.Sleep(2 * time.Second); err = bdSync(ctx)
}
return err

Prevention

Ensure the bd SQL user has SELECT grants on the metadata table
Use stable network paths to the Dolt server (avoid flaky proxies)
Set realistic query timeouts for remote servers
Retry transient wrapped errors; escalate persistent ones to server logs

When it happens

Trigger: GetMetadataInTx(ctx, conn, "_project_id") returns an error during verifyTeamServerSchema — e.g. SQL error, connection drop mid-query, permission denial on the metadata table, or ctx cancellation.

Common situations: Transient network failure to the Dolt server during connect; revoked/insufficient SQL grants on the metadata table; server-side error while reading metadata; ctx timeout expiring mid-query.

Related errors

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