gastownhall/beads · error

dolt server not reachable: %w

Error message

dolt server not reachable: %w

What it means

openDoltDB opens a SQL connection to the local Dolt server during `bd doctor` fix/validation checks and, after dialing, calls db.Ping() to verify the server actually answers. If the ping fails, it closes the connection and wraps the driver error with this message. It means the TCP listener may exist (the dial succeeded) but the server is not responding to a live handshake/query — or the dial itself failed and the wrapped error carries that detail.

Source

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

// 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 in the repository (e.g. `bd dolt server` or `dolt sql-server`) and re-run the doctor command.
2. Verify the server is listening: `dolt sql -q 'select 1'` or check the port with `ss -ltnp`/`lsof -i :<port>`.
3. Check bd's Dolt connection config (host/port/database in .beads config) matches the running server.
4. If the server is mid-start, wait and retry; if it repeatedly crashes, inspect the Dolt server logs.

Example fix

// before (server down)
$ bd doctor fix-missing-dolt-db
dolt server not reachable: dial tcp 127.0.0.1:3307: connect: connection refused

// after
$ bd dolt server &
$ bd doctor fix-missing-dolt-db
OK

func doltReachable(port int) bool {
	conn, err := net.DialTimeout("tcp", fmt.Sprintf("127.0.0.1:%d", port), 2*time.Second)
	if err != nil {
		return false
	}
	conn.Close()
	return true
}
// call before running doctor fix commands; start the server if false

db, cfg, err := openDoltDB()
if err != nil {
	var inner error
	if errors.As(err, &inner) && strings.Contains(err.Error(), "not reachable") {
		// surface hint: run `bd dolt server` before retrying
	}
	return fmt.Errorf("doctor check skipped: %w", err)
}

When it happens

Trigger: Any of the doctor commands that open the DB (RecomputeBlocked, ScanSeveredCloneLocalFKs, CloneLocalFKEnforcement, DependencyKeys, FixMissingDoltDatabase, OrphanedDependencies) run while the Dolt server process is down, listening on the wrong port/host, still starting up, or rejecting the configured credentials/database.

Common situations: The user never ran `dolt sql-server` (or `bd dolt server`) in the repo; the server crashed or was killed; stale config points at a port another (dead) instance used; the server is bound to a socket/port that differs from bd's configuration; firewall or permission issues block localhost connections.

Related errors

• failed to load config: %w
• failed to commit is_blocked repairs to Dolt: %w
• failed to scan dependency keys: %w
• failed to begin transaction: %w
• failed to commit dependency key repairs: %w

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