{"record":{"id":"7e5b5bfea888d100","repo":"gastownhall/beads","slug":"uow-capture-fresh-database-identity-w","errorCode":null,"errorMessage":"uow: capture fresh database identity: %w","messagePattern":"uow: capture fresh database identity: %w","errorType":"exception","errorClass":"bootstrapPreparationError","httpStatus":null,"severity":"error","filePath":"internal/storage/uow/dolt_sql_provider.go","lineNumber":363,"sourceCode":"\t\t\t}\n\t\tdefault:\n\t\t\treturn nil, &bootstrapPreparationError{err: fmt.Errorf(\"uow: creating database: %w\", err)}\n\t\t}\n\t}\n\tif err := ddl.UseDatabase(ctx, b.database); err != nil {\n\t\treturn nil, &bootstrapPreparationError{err: fmt.Errorf(\"uow: switching to database: %w\", err)}\n\t}\n\tif justCreated {\n\t\t// Capture authority only in the same attempt that won the exact bare\n\t\t// CREATE. A later retry may re-create a missing database for\n\t\t// availability, but it must never infer ownership of a replacement\n\t\t// incarnation from CREATE IF NOT EXISTS.\n\t\tvar err error\n\t\tb.heal, err = schema.CaptureFreshBootstrapHealCapability(\n\t\t\tctx, conn, b.provider.serverEndpoint, b.database,\n\t\t)\n\t\tif err != nil {\n\t\t\treturn nil, &bootstrapPreparationError{err: fmt.Errorf(\"uow: capture fresh database identity: %w\", err)}\n\t\t}\n\t}\n\treturn b.heal, nil\n}\n\nfunc buildDSN(ep proxy.Endpoint, database, user, password, tlsConfigName string) string {\n\treturn util.DoltServerDSN{\n\t\tHost:            ep.Host,\n\t\tPort:            ep.Port,\n\t\tUser:            user,\n\t\tPassword:        password,\n\t\tDatabase:        database,\n\t\tTLSConfigName:   tlsConfigName,\n\t\tClientFoundRows: true,\n\t}.String()\n}\n\nfunc openDB(ctx context.Context, dsn string) (*sql.DB, error) {","sourceCodeStart":345,"sourceCodeEnd":381,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/dolt_sql_provider.go#L345-L381","documentation":"In the same attempt that won the bare CREATE DATABASE, prepare calls schema.CaptureFreshBootstrapHealCapability to record the fresh-bootstrap ownership proof (endpoint, server UUID, database, initial HEAD). This error wraps a failure of that identity capture in a bootstrapPreparationError. It is thrown because the heal capability could not be captured, so the one-shot self-heal guard cannot be armed for this bootstrap.","triggerScenarios":"CaptureFreshBootstrapHealCapability's queries against the just-created database fail — e.g. the underlying connection errors, the server cannot report its UUID/HEAD, or the database disappears between CREATE and capture (concurrent drop).","commonSituations":"Unstable connection to a loaded shared Dolt server; embedded server restarted between CREATE and capture; concurrent clean-databases removing the fresh database; server version that does not expose the metadata the capture queries expect.","solutions":["Retry bd init on a stable connection — the CREATE will report already-exists, bootstrap continues, only the heal capability is skipped.","Ensure no concurrent process drops the database during init.","Check Dolt server version compatibility and that the server reports its UUID/HEAD correctly.","Inspect the wrapped driver error from the capture queries for the precise root cause."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Before init: verify server exposes required metadata and is stable\nconn, err := sql.Open(\"mysql\", dsnWithoutDB)\nif err != nil { return err }\nif err := conn.PingContext(ctx); err != nil {\n    return fmt.Errorf(\"server unreachable: %w\", err)\n}","typeGuard":"func isBootstrapPreparationError(err error) (*uow.BootstrapPreparationError, bool) {\n    var bpe *uow.BootstrapPreparationError\n    if errors.As(err, &bpe) {\n        return bpe, true\n    }\n    return nil, false\n}","tryCatchPattern":"err := initProvider(ctx)\nif err != nil {\n    var bpe *uow.BootstrapPreparationError\n    if errors.As(err, &bpe) && strings.Contains(bpe.Error(), \"capture fresh database identity\") {\n        // heal capability not captured; init can be retried safely\n        return retryWithBackoff(ctx)\n    }\n    return err\n}","preventionTips":["Init on a stable, non-loaded server connection","Ensure no concurrent process drops the freshly created database","Keep Dolt server version current so identity metadata queries succeed","Treat loss of the heal capability as non-fatal and re-run init"],"tags":["database","bootstrap","dolt","migration"],"backgroundTag":"bootstrap-identity-capture-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}