gastownhall/beads · error

uow: rootUser must not be empty

Error message

uow: rootUser must not be empty

What it means

The provider requires a non-empty rootUser, the Dolt superuser account used to administer/create the target database on the external Dolt SQL server. This guard exists because subsequent bootstrap steps (connecting as root, creating or healing the database) cannot proceed without it. It is a fail-fast validation before any network or filesystem work happens.

Source

Thrown at internal/storage/uow/external_doltserver_provider.go:39

	database string,
	serverLogFilePath string,
	external configfile.ExternalDoltConfig,
	rootUser string,
	rootPassword 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 rootUser == "" {
		return nil, fmt.Errorf("uow: rootUser must not be empty")
	}
	if err := external.Validate(); err != nil {
		return nil, fmt.Errorf("uow: external: %w", err)
	}

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

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

	tlsConfigName, err := registerExternalTLSConfig(external)
	if err != nil {
		return nil, fmt.Errorf("uow: external TLS: %w", err)
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Pass the Dolt root username explicitly via the rootUser parameter or the appropriate ProviderOption
2. Check the external-server config section for an empty root-user field and fill it in (typically "root")
3. Verify the env var or secret backing the root user actually resolves to a non-empty value in the runtime environment

Example fix

// before
provider, err := uow.NewExternalDoltServerUOWProvider(ctx, db, "", serverRoot, external)
// after
provider, err := uow.NewExternalDoltServerUOWProvider(ctx, db, "root", serverRoot, external)

if rootUser == "" {
    return fmt.Errorf("config: external dolt rootUser is required (usually \"root\")")
}

func hasRootUser(user string) bool {
    return strings.TrimSpace(user) != ""
}

provider, err := uow.NewExternalDoltServerUOWProvider(ctx, db, root, dir, ext)
if err != nil {
    if strings.Contains(err.Error(), "rootUser must not be empty") {
        return fmt.Errorf("misconfiguration: external-server rootUser missing: %w", err)
    }
    return err
}

When it happens

Trigger: Calling NewExternalDoltServerUOWProvider with rootUser == "" — e.g. config omitted the root user, an empty env var was passed through, or openProvider forwarded an unset field.

Common situations: External-server configuration (dolt server address/credentials) partially filled in; a deployment template left the root user blank; a migration from embedded mode to external server mode missed the new credential fields.

Related errors

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

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