gastownhall/beads · error

uow: doltBinExec must not be empty

Error message

uow: doltBinExec must not be empty

What it means

NewDoltServerUOWProvider needs the path to the dolt binary (doltBinExec) so it can launch/manage the Dolt SQL server. An empty path is rejected before any filesystem work. Without it the proxy cannot spawn or supervise the server process.

Source

Thrown at internal/storage/uow/doltserver_provider.go:45

	idleTimeout time.Duration,
	teamServer bool,
	expectedProjectID string,
	opts ...ProviderOption,
) (UnitOfWorkProvider, error) {
	if idleTimeout == 0 {
		idleTimeout = defaultProxyIdleTimeout
	}
	if database == "" {
		return nil, fmt.Errorf("uow: database name must not be empty (caller should default to %q)", "beads")
	}
	if err := backend.Validate(); err != nil {
		return nil, fmt.Errorf("uow: backend: %w", err)
	}
	if rootUser == "" {
		return nil, fmt.Errorf("uow: rootUser must not be empty")
	}
	if doltBinExec == "" {
		return nil, fmt.Errorf("uow: doltBinExec must not be empty")
	}

	absServerRootDir, err := filepath.Abs(serverRootDir)
	if err != nil {
		return nil, fmt.Errorf("uow: resolving server root dir: %w", err)
	}
	absDoltBinExec, err := filepath.Abs(doltBinExec)
	if err != nil {
		return nil, fmt.Errorf("uow: resolving dolt bin exec: %w", err)
	}

	if err := os.MkdirAll(absServerRootDir, config.BeadsDirPerm); err != nil {
		return nil, fmt.Errorf("uow: creating server root directory: %w", err)
	}

	ep, err := proxy.GetCreateDatabaseProxyServerEndpoint(absServerRootDir, proxy.OpenOpts{
		Backend:        backend,
		ConfigFilePath: serverConfigFilePath,

View on GitHub (pinned to 71377f2769)

Solutions

1. Install dolt and pass its resolved path, e.g. from exec.LookPath("dolt")
2. Fail early with a clear message if LookPath returns an error instead of passing ""
3. Set the binary path explicitly in config for non-standard installs

Example fix

// before
prov, err := NewDoltServerUOWProvider(ctx, dir, db, log, cfg, backend, "root", "", cfg.DoltBin, ...)
// after
doltBin, err := exec.LookPath("dolt")
if err != nil { return fmt.Errorf("dolt binary not found: %w", err) }
prov, err := NewDoltServerUOWProvider(ctx, dir, db, log, cfg, backend, "root", "", doltBin, ...)

doltBin, err := exec.LookPath("dolt")
if err != nil {
    return fmt.Errorf("dolt binary not found on PATH; install dolt first: %w", err)
}
// pass doltBin as doltBinExec

func doltBinaryAvailable(path string) bool {
    if path == "" { return false }
    p, err := exec.LookPath(path)
    return err == nil && p != ""
}

prov, err := NewDoltServerUOWProvider(..., doltBin, ...)
if err != nil && strings.Contains(err.Error(), "doltBinExec must not be empty") {
    return fmt.Errorf("install dolt or set dolt_bin in config: %w", err)
}

When it happens

Trigger: Calling NewDoltServerUOWProvider with doltBinExec == "", typically because the dolt binary was not found on PATH and the lookup returned an empty string, or the config field was never set.

Common situations: Dolt not installed; exec.LookPath("dolt") result ignored; container images missing the dolt binary; config default pointing at a variable that resolved to empty.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• ExternalDoltConfig: Port %d out of range [1, 65535]
• database name cannot be empty
• uow: database name must not be empty (caller should default
• uow: rootUser must not be empty
• uow: external: %w

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