gastownhall/beads · error

dolt server connection failed: %w

Error message

dolt server connection failed: %w

What it means

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.

Source

Thrown at cmd/bd/doctor/fix/validation.go:332

		return 0, fmt.Errorf("query cross-table duplicates: %w", err)
	}
	return count, nil
}

// openDoltDB opens a Dolt database connection via MySQL protocol.
// Delegates to openFixDB for DSN construction (timeout + password support).
// Also returns the loaded config so callers that need it afterward (e.g. to
// verify the connection's target identity) don't have to load it a second
// time and risk it disagreeing with what was actually dialed.
func openDoltDB(beadsDir string) (*sql.DB, *configfile.Config, error) {
	cfg, err := configfile.Load(beadsDir)
	if err != nil || cfg == nil {
		return nil, nil, fmt.Errorf("no database configuration found")
	}

	db, err := openFixDB(beadsDir, cfg)
	if err != nil {
		return nil, nil, fmt.Errorf("dolt server connection failed: %w", err)
	}

	// Verify the connection actually works
	if err := db.Ping(); err != nil {
		_ = db.Close() // Best effort cleanup
		return nil, nil, fmt.Errorf("dolt server not reachable: %w", err)
	}

	return db, cfg, nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Start the Dolt server: run `dolt sql-server` in the database directory (or `bd dolt ...` start step) and retry the doctor fix
2. Check .beads config.json server host/port match where `dolt sql-server` is actually listening
3. Test connectivity manually: `mysql -h <host> -P <port> -u <user> -p <database>` or `dolt sql -q 'SELECT 1'`
4. Fix credentials in the config if the wrapped error is an auth/access-denied failure
5. Check firewalls/port forwarding (WSL, Docker, remote hosts) for the configured port

Example fix

// before: server not running, fix skips
  Child-parent dependencies fix skipped (dolt server connection failed: dial tcp 127.0.0.1:3307: connect: connection refused)
// after: start the server first
$ cd .beads/dolt && dolt sql-server &
$ bd doctor --fix

// Verify the Dolt server is listening before running fixes
conn, err := net.DialTimeout("tcp", net.JoinHostPort(cfg.Host, cfg.Port), 3*time.Second)
if err != nil {
    return fmt.Errorf("dolt sql-server not listening on %s:%s — start it first", cfg.Host, cfg.Port)
}
conn.Close()

db, cfg, err := openDoltDB(beadsDir)
if err != nil {
    if strings.Contains(err.Error(), "dolt server connection failed") {
        // attempt one restart + retry
        if startErr := startDoltServer(beadsDir); startErr == nil {
            db, cfg, err = openDoltDB(beadsDir)
        }
    }
    if err != nil {
        return fmt.Errorf("cannot reach dolt server: %w", err)
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• uow: ping db: %w
• dolt server unreachable at %s:%d (is dolt sql-server running
• failed to open server connection: %w
• server not reachable: %w
• failed to query cross-table duplicates: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/6865a208d1dae966. Report an issue: GitHub.