What causes "uow: rootUser must not be empty" in gastownhall/beads?

Pass "root" (or your configured admin user) as rootUser

uow: rootUser must not be empty

Error message

uow: rootUser must not be empty

What it means

NewDoltServerUOWProvider requires a non-empty root SQL user name used to connect and run schema DDL. An empty rootUser is rejected up front. Without it the MySQL DSN would be malformed or the server would fall back to an unintended authenticated user.

Source

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

	rootPassword string,
	doltBinExec string,
	proxyPort int,
	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)
	}

View on GitHub (pinned to 71377f2769)

Solutions

Pass "root" (or your configured admin user) as rootUser
Default from config: if user == "" { user = "root" }
Verify the config file/env actually populates the user field

Example fix

// before
prov, err := NewDoltServerUOWProvider(ctx, dir, db, log, cfg, backend, cfg.User, ...)
// after
user := cfg.User
if user == "" { user = "root" }
prov, err := NewDoltServerUOWProvider(ctx, dir, db, log, cfg, backend, user, ...)

Defensive patterns

Strategy: validation

Validate before calling

if rootUser == "" {
    return errors.New("rootUser required (use \"root\" for the Dolt admin user)")
}
// call before NewDoltServerUOWProvider

Type guard

func hasRootUser(cfg Config) bool { return strings.TrimSpace(cfg.RootUser) != "" }

Try / catch

if err := validateRootUser(rootUser); err != nil { return err }
prov, err := NewDoltServerUOWProvider(..., rootUser, ...)
if err != nil && strings.Contains(err.Error(), "rootUser must not be empty") {
    return fmt.Errorf("config error: %w", err)
}

Prevention

Default rootUser to "root" at config load when unset
Never read credentials fields without a presence check
Document required provider arguments in the config template

When it happens

Trigger: Calling NewDoltServerUOWProvider with rootUser == "", usually from an unset config key or env var holding the Dolt server superuser.

Common situations: Config migration dropped the user field; caller assumed a default root user exists; password set but username field left blank.

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

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