gastownhall/beads · warning

uow: team-server identity check: %w

Error message

uow: team-server identity check: %w

What it means

This error wraps a failure from checkTeamServerIdentity during verifyTeamServerSchema in the unit-of-work bootstrap path. When bd opens a team-server database, it verifies that the database's project identity metadata matches the expectedProjectID configured for this workspace. If the identity query hits a serialization conflict (a transient driver/transaction conflict on a shared Dolt server), the error is classified as retryable and wrapped so the surrounding backoff.Retry loop can re-attempt the whole schema check.

Source

Thrown at internal/storage/uow/dolt_sql_provider.go:262

func (p *doltSQLProvider) verifyTeamServerSchema(ctx context.Context, conn *sql.Conn, database string) error {
	ddl := db.NewDDLSQLRepository(conn)
	if err := ddl.UseDatabase(ctx, database); err != nil {
		if isSerializationError(err) {
			return fmt.Errorf("uow: switching to database: %w", err)
		}
		return backoff.Permanent(fmt.Errorf(
			"uow: database %q not found — the schema is managed by beads-team-server; ask your operator to run 'bts init' first: %w",
			database, err))
	}
	if err := checkTeamServerSchema(ctx, conn, database); err != nil {
		if isSerializationError(err) {
			return fmt.Errorf("uow: team-server schema check: %w", err)
		}
		return backoff.Permanent(err)
	}
	if err := checkTeamServerIdentity(ctx, conn, database, p.expectedProjectID); err != nil {
		if isSerializationError(err) {
			return fmt.Errorf("uow: team-server identity check: %w", err)
		}
		return backoff.Permanent(err)
	}
	return nil
}

// attachPreviewDatabase is the preview open path: attach to the database that is
// already there and stop. No CreateDatabase, no MigrateUpWithLock — a --dry-run
// or --inspect that migrated the workspace before rendering its plan would be the
// exact side effect the flag exists to prevent.
func (p *doltSQLProvider) attachPreviewDatabase(ctx context.Context, conn *sql.Conn, database string) error {
	ddl := db.NewDDLSQLRepository(conn)
	if err := ddl.UseDatabase(ctx, database); err != nil {
		if isSerializationError(err) {
			return fmt.Errorf("uow: switching to database: %w", err)
		}
		return backoff.Permanent(fmt.Errorf(
			"uow: database %q not found — preview commands (--dry-run, --inspect) never create or migrate a database; run the command without the preview flag first: %w",

View on GitHub (pinned to 71377f2769)

Solutions

1. Simply retry the bd command — this error is intentionally classified retryable and the backoff loop (up to 60s) usually resolves it; if you saw it, the retry may have already succeeded.
2. Reduce concurrent access: ensure beads-team-server is the sole schema owner and clients aren't running migrations/init against the same database simultaneously.
3. Check server load and connectivity to the shared Dolt server (latency, connection limits) and increase capacity or tune backoff if conflicts recur.
4. If it fails permanently instead, run bd doctor / verify the project identity configured in the workspace matches the database created by 'bts init'.

func isRetryableUOWError(err error) bool {
	var permanent *backoff.PermanentError
	return err != nil && !errors.As(err, &permanent)
}

err := bdCommand(ctx)
if err != nil {
	var perm *backoff.PermanentError
	if !errors.As(err, perm) { // serialization-wrapped: safe to retry
		err = retry.Do(ctx, bdCommand, retry.WithBackoff(60*time.Second))
	}
	if err != nil {
		return fmt.Errorf("team-server identity check failed: %w", err)
	}
}

When it happens

Trigger: Calling any bd command that opens a team-server-mode workspace (p.teamServer=true) when checkTeamServerIdentity's query against the metadata table returns a serialization-classified error (per isSerializationError), typically under concurrent access on a loaded shared Dolt server. Note this only fires for the serialization branch; a real identity mismatch returns backoff.Permanent(err) directly without this message.

Common situations: Multiple bd clients or beads-team-server processes hammering the same shared Dolt server concurrently; a busy server under load where transaction conflicts are frequent; transient network/connection flakiness to a remote team server mid-init.

Related errors

• uow: switching to database: %w
• uow: team-server schema check: %w
• record repo_id: %w
• record clone_id: %w
• record last_import_time: %w

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