What causes "server: NewDoltServer: doltBinExec is required" in gastownhall/beads?

Set the dolt binary path from config or env (e.g. DOLT_BIN) before constructing the server

server: NewDoltServer: doltBinExec is required

Error message

server: NewDoltServer: doltBinExec is required

What it means

NewDoltServer validates its required parameters and returns this error when doltBinExec is empty. The server needs the path to the dolt binary to spawn the backend; without it there is nothing to exec.

Source

Thrown at internal/storage/dbproxy/server/doltserver.go:65

	doltBinExec     string
	rootDir         string
	configPath      string
	database        string
	config          servercfg.ServerConfig
	keepAlivePeriod time.Duration

	logFile *os.File
	eg      *errgroup.Group
	egCtx   context.Context
	cancel  context.CancelFunc
	pid     int
}

var _ DatabaseServer = (*DoltServer)(nil)

func NewDoltServer(doltBinExec, rootDir, configPath, logFilePath string, keepAlivePeriod time.Duration, database string) (*DoltServer, error) {
	if doltBinExec == "" {
		return nil, errors.New("server: NewDoltServer: doltBinExec is required")
	}
	if rootDir == "" {
		return nil, errors.New("server: NewDoltServer: rootDir is required")
	}
	if configPath == "" {
		return nil, errors.New("server: NewDoltServer: configPath is required")
	}
	absDoltBinExec, err := filepath.Abs(doltBinExec)
	if err != nil {
		return nil, errors.New("server: NewDoltServer: failed to determine absolute path of doltBinExec")
	}
	absRootDir, err := filepath.Abs(rootDir)
	if err != nil {
		return nil, errors.New("server: NewDoltServer: failed to determine absolute path of rootDir")
	}
	absConfigPath, err := filepath.Abs(configPath)
	if err != nil {
		return nil, errors.New("server: NewDoltServer: failed to determine absolute path of configPath")

View on GitHub (pinned to 71377f2769)

Solutions

Set the dolt binary path from config or env (e.g. DOLT_BIN) before constructing the server
Default to a known installed path (e.g. from PATH lookup via exec.LookPath("dolt"))
Validate configuration at load time so empty binary paths fail early

Example fix

// before
srv, err := server.NewDoltServer(cfg.DoltBin, root, cfgPath, logPath, ka, db) // cfg.DoltBin == ""
// after
doltBin := cfg.DoltBin
if doltBin == "" {
    doltBin, err = exec.LookPath("dolt")
}
srv, err := server.NewDoltServer(doltBin, root, cfgPath, logPath, ka, db)

Defensive patterns

Strategy: validation

Validate before calling

if doltBin == "" {
    p, err := exec.LookPath("dolt")
    if err != nil { return fmt.Errorf("dolt binary not configured or on PATH: %w", err) }
    doltBin = p
}

Try / catch

srv, err := server.NewDoltServer(doltBin, root, cfgPath, logPath, ka, db)
if err != nil && strings.Contains(err.Error(), "doltBinExec is required") {
    return fmt.Errorf("set DOLT_BIN or install dolt on PATH: %w", err)
}

Prevention

Resolve the dolt binary path (env/config/PATH) before server construction
Fail fast at config load if the binary path is empty
Keep tests providing a fixture binary path

When it happens

Trigger: Calling server.NewDoltServer("", ...) with an unset or empty dolt binary path variable.

Common situations: Missing DOLT_BIN environment variable or config key; config struct zero-valued because it was never populated; constructor called in tests without fixtures.

Related errors

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