{"record":{"id":"7ffc0bcfbaa4d60e","repo":"gastownhall/beads","slug":"schema-capture-fresh-bootstrap-identity-w","errorCode":null,"errorMessage":"schema: capture fresh-bootstrap identity: %w","messagePattern":"schema: capture fresh-bootstrap identity: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/schema/lock.go","lineNumber":117,"sourceCode":"// set. Any uncertainty fails closed instead of issuing reset authority.\nfunc CaptureFreshBootstrapHealCapability(\n\tctx context.Context,\n\tconn *sql.Conn,\n\tendpoint string,\n\texpectedDatabase string,\n) (*FreshBootstrapHealCapability, error) {\n\tif endpoint == \"\" {\n\t\treturn nil, errors.New(\"schema: capture fresh-bootstrap identity: empty endpoint\")\n\t}\n\tif expectedDatabase == \"\" {\n\t\treturn nil, errors.New(\"schema: capture fresh-bootstrap identity: empty database name\")\n\t}\n\n\tvar databaseName, serverUUID, initialHead string\n\tif err := conn.QueryRowContext(ctx,\n\t\t\"SELECT DATABASE(), @@server_uuid, DOLT_HASHOF('HEAD')\",\n\t).Scan(&databaseName, &serverUUID, &initialHead); err != nil {\n\t\treturn nil, fmt.Errorf(\"schema: capture fresh-bootstrap identity: %w\", err)\n\t}\n\tif databaseName != expectedDatabase {\n\t\treturn nil, fmt.Errorf(\"schema: capture fresh-bootstrap identity: database is %q, want %q\", databaseName, expectedDatabase)\n\t}\n\tif serverUUID == \"\" {\n\t\treturn nil, errors.New(\"schema: capture fresh-bootstrap identity: empty server UUID\")\n\t}\n\tif initialHead == \"\" {\n\t\treturn nil, errors.New(\"schema: capture fresh-bootstrap identity: empty initial HEAD\")\n\t}\n\n\tvar commitCount, dirtyCount int\n\tif err := conn.QueryRowContext(ctx, \"SELECT COUNT(*) FROM dolt_log\").Scan(&commitCount); err != nil {\n\t\treturn nil, fmt.Errorf(\"schema: verify fresh-bootstrap history: %w\", err)\n\t}\n\tif commitCount != 1 {\n\t\treturn nil, fmt.Errorf(\"schema: verify fresh-bootstrap history: got %d commits, want 1\", commitCount)\n\t}","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/schema/lock.go#L99-L135","documentation":"CaptureFreshBootstrapHealCapability failed while running its identity probe `SELECT DATABASE(), @@server_uuid, DOLT_HASHOF('HEAD')` on the pinned connection, right after a bare CREATE DATABASE. The library wraps the underlying SQL driver error so the caller knows bootstrap-identity capture, not migration itself, failed. Because capture authority is issued fail-closed, any probe error means no fresh-bootstrap heal capability is produced.","triggerScenarios":"Calling CaptureFreshBootstrapHealCapability when the connection is broken, the session has no database selected (DATABASE() is fine but @@server_uuid/DOLT_HASHOF fail), the server is not Dolt-aware (DOLT_HASHOF unknown), or the context is cancelled/times out mid-query.","commonSituations":"Connecting to a non-Dolt MySQL server that lacks DOLT_HASHOF; a pooled connection dropped by an idle timeout; a Dolt sql-server restarting during init; a ctx deadline expiring because the server is slow to accept the new database.","solutions":["Inspect the wrapped cause (%w) to identify the actual driver error; fix that first (e.g. reconnect, correct server).","Verify you are connecting to a Dolt sql-server that supports DOLT_HASHOF and @@server_uuid.","Ensure the session has a database selected or the DSN names the database before capture.","Retry the whole open/bootstrap; the capability is designed to fail closed and the caller's retry loop should re-run CREATE DATABASE + capture."],"exampleFix":"// before\nconn, _ := pool.Conn(ctx)\ncap, err := schema.CaptureFreshBootstrapHealCapability(ctx, conn, endpoint, dbName) // fails: server lacks DOLT_HASHOF\n// after\n// point endpoint at the Dolt sql-server, and pass a bounded ctx\nctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)\ndefer cancel()\ncap, err := schema.CaptureFreshBootstrapHealCapability(ctx, conn, doltEndpoint, dbName)","handlingStrategy":"retry","validationCode":"if endpoint == \"\" || dbName == \"\" { return errors.New(\"endpoint and database name are required\") }\nif err := conn.PingContext(ctx); err != nil { return fmt.Errorf(\"connection not usable: %w\", err) }","typeGuard":"func isCaptureProbeFailure(err error) bool {\n\treturn err != nil && strings.Contains(err.Error(), \"capture fresh-bootstrap identity:\") && !strings.Contains(err.Error(), \"want\")\n}","tryCatchPattern":"cap, err := schema.CaptureFreshBootstrapHealCapability(ctx, conn, endpoint, db)\nif err != nil {\n\tif ctx.Err() != nil { return ctx.Err() }\n\t// fail closed: no heal authority; retry whole open/bootstrap\n\treturn fmt.Errorf(\"bootstrap capture failed: %w\", err)\n}","preventionTips":["Always point at a Dolt sql-server, never plain MySQL, for beads storage.","Ping the pinned connection before capture and use a bounded context.","Retry the full create-database + capture sequence on transient failure.","Keep the pinned session free of undrained result sets."],"tags":["go","database","dolt","bootstrap","schema-migration"],"backgroundTag":"dolt-bootstrap-identity-probe-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}