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.

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 argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• database name cannot be empty
• ExternalDoltConfig: Port
• uow: database name must not be empty
• uow: external
• uow: rootUser must not be empty

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

Appendix: 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)