{"record":{"id":"b41f8dcb3d96b3a7","repo":"gastownhall/beads","slug":"failed-to-open-dolt-server-connection-w","errorCode":null,"errorMessage":"failed to open Dolt server connection: %w","messagePattern":"failed to open Dolt server connection: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/store.go","lineNumber":2371,"sourceCode":"\n\t// alreadyExisted reports whether the database was proven to exist on the\n\t// server before this call: either the SHOW DATABASES probe found it, or\n\t// our CREATE DATABASE was refused with \"database exists\" (1007). Callers\n\t// use it to decide whether project-identity verification applies even\n\t// when CreateIfMissing is true (see the newServerMode gate around\n\t// verifyProjectIdentity, GH#4637).\n\talreadyExisted bool\n}\n\n// openServerConnection connects to (and if needed creates) the target database\n// on a dolt sql-server via MySQL protocol. See serverConnFacts for what the\n// returned facts mean and why they are not a single bool.\nfunc openServerConnection(ctx context.Context, cfg *Config) (*sql.DB, string, serverConnFacts, error) {\n\tconnStr := buildServerDSN(cfg, cfg.Database)\n\n\tdb, err := sql.Open(\"mysql\", connStr)\n\tif err != nil {\n\t\treturn nil, \"\", serverConnFacts{}, fmt.Errorf(\"failed to open Dolt server connection: %w\", err)\n\t}\n\n\t// Configure the pool. *sql.DB is safe for concurrent use and manages its\n\t// own pool — the same Store reuses these connections across every query\n\t// for the lifetime of the daemon, rather than opening a fresh one each\n\t// time (which used to show up as endless NewConnection/ConnectionClosed\n\t// pairs in dolt-server.log).\n\tapplyPoolLimits(db, cfg)\n\n\t// Close the pool on any failure path below; cleared at the success return.\n\tconnReady := false\n\tdefer func() {\n\t\tif !connReady {\n\t\t\t_ = db.Close()\n\t\t}\n\t}()\n\n\t// A gateway server owns database routing and existence, so bd does not probe or create","sourceCodeStart":2353,"sourceCodeEnd":2389,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/store.go#L2353-L2389","documentation":"openServerConnection establishes the main pooled connection to a remote Dolt server via sql.Open(\"mysql\", connStr). This error wraps sql.Open failure when creating the server connection; it indicates driver/config problems at the very start of server-mode open.","triggerScenarios":"Opening a store in server mode where buildServerDSN(cfg, cfg.Database) yields a DSN that sql.Open rejects (driver missing, malformed DSN).","commonSituations":"Misconfigured server host/port producing an invalid DSN; mysql driver not linked; corrupted config values interpolated into the DSN.","solutions":["Validate the DSN produced from cfg (host, port, database, credentials)","Ensure the mysql driver is imported in the binary","Fix config values in metadata.json / flags and retry open","Run bd dolt status to cross-check connection settings"],"exampleFix":"// before\ncfg.ServerHost = \"localhost:not-a-port\"\n// after\ncfg.ServerHost = \"localhost\"\ncfg.ServerPort = 3307","handlingStrategy":"try-catch","validationCode":"connStr := buildServerDSN(cfg, cfg.Database)\nif _, err := mysql.ParseDSN(connStr); err != nil {\n    return fmt.Errorf(\"server DSN invalid: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"store, err := OpenStore(ctx, cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to open Dolt server connection\") {\n        // inspect cfg host/port/database before retry\n    }\n    return err\n}","preventionTips":["Validate ServerHost/ServerPort/Database before open","Escape credentials in buildServerDSN","Ensure mysql driver is linked in server-mode builds","Run bd dolt status to confirm settings match the running server"],"tags":["database","connection","dsn","configuration"],"backgroundTag":"sql-open-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}