{"record":{"id":"6865a208d1dae966","repo":"gastownhall/beads","slug":"dolt-server-connection-failed-w","errorCode":null,"errorMessage":"dolt server connection failed: %w","messagePattern":"dolt server connection failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/doctor/fix/validation.go","lineNumber":332,"sourceCode":"\t\treturn 0, fmt.Errorf(\"query cross-table duplicates: %w\", err)\n\t}\n\treturn count, nil\n}\n\n// openDoltDB opens a Dolt database connection via MySQL protocol.\n// Delegates to openFixDB for DSN construction (timeout + password support).\n// Also returns the loaded config so callers that need it afterward (e.g. to\n// verify the connection's target identity) don't have to load it a second\n// time and risk it disagreeing with what was actually dialed.\nfunc openDoltDB(beadsDir string) (*sql.DB, *configfile.Config, error) {\n\tcfg, err := configfile.Load(beadsDir)\n\tif err != nil || cfg == nil {\n\t\treturn nil, nil, fmt.Errorf(\"no database configuration found\")\n\t}\n\n\tdb, err := openFixDB(beadsDir, cfg)\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"dolt server connection failed: %w\", err)\n\t}\n\n\t// Verify the connection actually works\n\tif err := db.Ping(); err != nil {\n\t\t_ = db.Close() // Best effort cleanup\n\t\treturn nil, nil, fmt.Errorf(\"dolt server not reachable: %w\", err)\n\t}\n\n\treturn db, cfg, nil\n}\n","sourceCodeStart":314,"sourceCodeEnd":343,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/doctor/fix/validation.go#L314-L343","documentation":"After loading config, openDoltDB calls openFixDB(beadsDir, cfg) which builds a MySQL-protocol DSN (with timeout and optional password) and dials the Dolt server. If dialing fails, the cause is wrapped as \"dolt server connection failed: %w\". Unlike the 'not reachable' error that follows (a failed Ping), this fires at the connection-establishment stage itself.","triggerScenarios":"openFixDB fails because no MySQL-protocol server is listening on the configured host:port (dolt sql-server not started), wrong host/port in .beads config, credentials rejected at handshake, or unsupported DSN/timeout configuration.","commonSituations":"Dolt server never started (`dolt sql-server` not running) or crashed; WSL/port-forward setups where the server binds a different interface; config.json pointing at a stale port after a restart; wrong password after credential rotation; firewall blocking the port.","solutions":["Start the Dolt server: run `dolt sql-server` in the database directory (or `bd dolt ...` start step) and retry the doctor fix","Check .beads config.json server host/port match where `dolt sql-server` is actually listening","Test connectivity manually: `mysql -h <host> -P <port> -u <user> -p <database>` or `dolt sql -q 'SELECT 1'`","Fix credentials in the config if the wrapped error is an auth/access-denied failure","Check firewalls/port forwarding (WSL, Docker, remote hosts) for the configured port"],"exampleFix":"// before: server not running, fix skips\n  Child-parent dependencies fix skipped (dolt server connection failed: dial tcp 127.0.0.1:3307: connect: connection refused)\n// after: start the server first\n$ cd .beads/dolt && dolt sql-server &\n$ bd doctor --fix","handlingStrategy":"retry","validationCode":"// Verify the Dolt server is listening before running fixes\nconn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(cfg.Host, cfg.Port), 3*time.Second)\nif err != nil {\n    return fmt.Errorf(\"dolt sql-server not listening on %s:%s — start it first\", cfg.Host, cfg.Port)\n}\nconn.Close()","typeGuard":null,"tryCatchPattern":"db, cfg, err := openDoltDB(beadsDir)\nif err != nil {\n    if strings.Contains(err.Error(), \"dolt server connection failed\") {\n        // attempt one restart + retry\n        if startErr := startDoltServer(beadsDir); startErr == nil {\n            db, cfg, err = openDoltDB(beadsDir)\n        }\n    }\n    if err != nil {\n        return fmt.Errorf(\"cannot reach dolt server: %w\", err)\n    }\n}","preventionTips":["Ensure `dolt sql-server` is running before doctor fix operations (add a startup check)","Keep server host/port in .beads/config.json in sync with how the server is launched","Test with `mysql` client or `dolt sql -q 'SELECT 1'` after config changes","Watch for connection-refused after server restarts — ports can change; update config","For WSL/remote setups, verify port forwarding and firewall rules for the MySQL protocol port"],"tags":["database","connection","mysql","dolt","network"],"backgroundTag":"connection-refused","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}