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

NewExternalDoltServerUOWProvider validates its inputs before creating a unit-of-work provider backed by an external Dolt server. The database name is mandatory because the provider must know which Dolt database to open and manage. The error message hints that the caller should have applied a default of "beads" before calling, so this error indicates a configuration gap that is normally handled by the caller layer.

Source

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

func NewExternalDoltServerUOWProvider(
	ctx context.Context,
	serverRootDir string,
	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)

View on GitHub (pinned to 71377f2769)

Solutions

Set the database name explicitly when calling NewExternalDoltServerUOWProvider
Default the value to "beads" at the call site if it is empty: if database == "" { database = "beads" }
Check where the database name comes from (config file / env var) and ensure the field is populated before provider construction

Example fix

// before
provider, err := uow.NewExternalDoltServerUOWProvider(ctx, cfg.Database, ...)
// after
dbName := cfg.Database
if dbName == "" {
    dbName = "beads"
}
provider, err := uow.NewExternalDoltServerUOWProvider(ctx, dbName, ...)

Defensive patterns

Strategy: validation

Validate before calling

if database == "" {
    database = "beads" // apply library default before calling
}
if err := validateNonEmpty(database); err != nil {
    return fmt.Errorf("config: database name missing: %w", err)
}

Type guard

func hasDatabaseName(db string) bool {
    return strings.TrimSpace(db) != ""
}

Try / catch

provider, err := uow.NewExternalDoltServerUOWProvider(ctx, db, root, dir, ext)
if err != nil {
    if strings.Contains(err.Error(), "database name must not be empty") {
        return fmt.Errorf("misconfiguration: set database (default \"beads\") in config: %w", err)
    }
    return err
}

Prevention

Always default the database name to "beads" at the config-loading layer
Validate config struct fields immediately after unmarshalling, before constructing providers
Add a unit test asserting config loading never yields an empty database name

When it happens

Trigger: Calling NewExternalDoltServerUOWProvider with database set to "" (empty string), e.g. when a config struct field was never populated, an env var resolved to empty, or openProvider forwarded an empty db name.

Common situations: A beads config file lacks a `database` key; BD_DATABASE or similar env var is set but empty; a custom integration constructs the provider directly without defaulting the database name as the CLI layer does.

Related errors

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