{"record":{"id":"76bcc7cd13bf5da7","repo":"gastownhall/beads","slug":"uow-team-server-identity-check-w","errorCode":null,"errorMessage":"uow: team-server identity check: %w","messagePattern":"uow: team-server identity check: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/storage/uow/dolt_sql_provider.go","lineNumber":262,"sourceCode":"func (p *doltSQLProvider) verifyTeamServerSchema(ctx context.Context, conn *sql.Conn, database string) error {\n\tddl := db.NewDDLSQLRepository(conn)\n\tif err := ddl.UseDatabase(ctx, database); err != nil {\n\t\tif isSerializationError(err) {\n\t\t\treturn fmt.Errorf(\"uow: switching to database: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(fmt.Errorf(\n\t\t\t\"uow: database %q not found — the schema is managed by beads-team-server; ask your operator to run 'bts init' first: %w\",\n\t\t\tdatabase, err))\n\t}\n\tif err := checkTeamServerSchema(ctx, conn, database); err != nil {\n\t\tif isSerializationError(err) {\n\t\t\treturn fmt.Errorf(\"uow: team-server schema check: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(err)\n\t}\n\tif err := checkTeamServerIdentity(ctx, conn, database, p.expectedProjectID); err != nil {\n\t\tif isSerializationError(err) {\n\t\t\treturn fmt.Errorf(\"uow: team-server identity check: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(err)\n\t}\n\treturn nil\n}\n\n// attachPreviewDatabase is the preview open path: attach to the database that is\n// already there and stop. No CreateDatabase, no MigrateUpWithLock — a --dry-run\n// or --inspect that migrated the workspace before rendering its plan would be the\n// exact side effect the flag exists to prevent.\nfunc (p *doltSQLProvider) attachPreviewDatabase(ctx context.Context, conn *sql.Conn, database string) error {\n\tddl := db.NewDDLSQLRepository(conn)\n\tif err := ddl.UseDatabase(ctx, database); err != nil {\n\t\tif isSerializationError(err) {\n\t\t\treturn fmt.Errorf(\"uow: switching to database: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(fmt.Errorf(\n\t\t\t\"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\",","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/dolt_sql_provider.go#L244-L280","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Reduce concurrent access: ensure beads-team-server is the sole schema owner and clients aren't running migrations/init against the same database simultaneously.","Check server load and connectivity to the shared Dolt server (latency, connection limits) and increase capacity or tune backoff if conflicts recur.","If it fails permanently instead, run bd doctor / verify the project identity configured in the workspace matches the database created by 'bts init'."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":"func isRetryableUOWError(err error) bool {\n\tvar permanent *backoff.PermanentError\n\treturn err != nil && !errors.As(err, &permanent)\n}","tryCatchPattern":"err := bdCommand(ctx)\nif err != nil {\n\tvar perm *backoff.PermanentError\n\tif !errors.As(err, perm) { // serialization-wrapped: safe to retry\n\t\terr = retry.Do(ctx, bdCommand, retry.WithBackoff(60*time.Second))\n\t}\n\tif err != nil {\n\t\treturn fmt.Errorf(\"team-server identity check failed: %w\", err)\n\t}\n}","preventionTips":["Avoid running many concurrent bd clients against the same team-server database; let beads-team-server arbitrate.","Monitor shared Dolt server load and tune capacity before large batch operations.","Keep client and bts versions aligned to reduce schema/identity re-check churn.","Treat this error class as transient: build retry-with-backoff into automation scripts."],"tags":["dolt","serialization","team-server","retry","unit-of-work"],"backgroundTag":"serialization-conflict-retryable","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}