uow: database name must not be empty (caller should default

Error message

uow: database name must not be empty (caller should default to %q)

What it means

NewDoltServerUOWProvider requires an explicit database name; passing an empty string is rejected immediately. The message tells the caller the library convention is to default to "beads" but does not apply the default itself. This is a fail-fast guard so a misconfigured provider never starts against a nameless database.

Source

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

	serverRootDir string,
	database string,
	serverLogFilePath string,
	serverConfigFilePath string,
	backend proxy.Backend,
	rootUser string,
	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)

View on GitHub (pinned to 71377f2769)

Solutions

Pass a non-empty database name, e.g. "beads"
If the value comes from config/env, apply a default: if db == "" { db = "beads" } before calling
Trim whitespace from user/config supplied names before validation

Example fix

// before
prov, err := NewDoltServerUOWProvider(ctx, dir, cfg.Database, ...)
// after
db := cfg.Database
if db == "" { db = "beads" }
prov, err := NewDoltServerUOWProvider(ctx, dir, db, ...)

Defensive patterns

Strategy: validation

Validate before calling

func validateDBName(db string) error {
    if strings.TrimSpace(db) == "" {
        return fmt.Errorf("database name required; default to %q", "beads")
    }
    return nil
}
// call before NewDoltServerUOWProvider

Type guard

func hasDatabaseName(cfg Config) bool { return strings.TrimSpace(cfg.Database) != "" }

Try / catch

if err := validateDBName(dbName); err != nil { return err }
prov, err := NewDoltServerUOWProvider(ctx, dir, dbName, ...)
if err != nil && strings.Contains(err.Error(), "database name must not be empty") {
    return fmt.Errorf("config error: %w", err)
}

Prevention

Apply the "beads" default at config-load time, not at call time
Trim and validate all string config values before constructing providers
Add a unit test asserting the config loader never yields an empty database name

When it happens

Trigger: Calling NewDoltServerUOWProvider with database == "", typically because the value came from an unset config field, empty env var, or an untrimmed CLI flag.

Common situations: BEADS_DB or similar env var unset; config file missing the database key; caller forgot to apply the "beads" default before constructing the provider.

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/22d7041c0b102d3b. Report an issue: GitHub.