--server-user cannot be empty; omit the flag to use BEADS_DO

Error message

--server-user cannot be empty; omit the flag to use BEADS_DOLT_SERVER_USER or the default (%s)

What it means

resolveExplicitServerConnEnv validates the --server-user flag when explicitly set. An explicitly empty value is rejected with this error pointing to the fallback order: BEADS_DOLT_SERVER_USER env var, then configfile.DefaultDoltServerUser. This mirrors the --server-host check and prevents flags from being silently dropped.

Source

Thrown at cmd/bd/init.go:3199

	var muts []serverConnEnvMutation
	if cmd.Flags().Changed("server-host") {
		v, _ := cmd.Flags().GetString("server-host")
		if v == "" {
			return nil, fmt.Errorf("--server-host cannot be empty; omit the flag to use BEADS_DOLT_SERVER_HOST or the default (%s)", configfile.DefaultDoltServerHost)
		}
		muts = append(muts, serverConnEnvMutation{key: "BEADS_DOLT_SERVER_HOST", value: v})
	}
	if cmd.Flags().Changed("server-port") {
		v, _ := cmd.Flags().GetInt("server-port")
		if v < 1 || v > 65535 {
			return nil, fmt.Errorf("--server-port must be between 1 and 65535, got %d; omit the flag to use BEADS_DOLT_SERVER_PORT or the default (%d)", v, configfile.DefaultDoltServerPort)
		}
		muts = append(muts, serverConnEnvMutation{key: "BEADS_DOLT_SERVER_PORT", value: strconv.Itoa(v)})
	}
	if cmd.Flags().Changed("server-user") {
		v, _ := cmd.Flags().GetString("server-user")
		if v == "" {
			return nil, fmt.Errorf("--server-user cannot be empty; omit the flag to use BEADS_DOLT_SERVER_USER or the default (%s)", configfile.DefaultDoltServerUser)
		}
		muts = append(muts, serverConnEnvMutation{key: "BEADS_DOLT_SERVER_USER", value: v})
	}
	switch {
	case cmd.Flags().Changed("server-socket"):
		v, _ := cmd.Flags().GetString("server-socket")
		if v == "" {
			muts = append(muts, serverConnEnvMutation{key: "BEADS_DOLT_SERVER_SOCKET", unset: true})
		} else {
			muts = append(muts, serverConnEnvMutation{key: "BEADS_DOLT_SERVER_SOCKET", value: v})
		}
	case cmd.Flags().Changed("server-host") || cmd.Flags().Changed("server-port"):
		muts = append(muts, serverConnEnvMutation{key: "BEADS_DOLT_SERVER_SOCKET", unset: true})
	}
	if cmd.Flags().Changed("server-tls") {
		v, _ := cmd.Flags().GetBool("server-tls")
		tls := "0"
		if v {

View on GitHub (pinned to 71377f2769)

Solutions

Pass a non-empty --server-user value
Export BEADS_DOLT_SERVER_USER=<user> and omit the flag
Rely on the default user by omitting both flag and env
Fix the surrounding script so the variable is set before invocation

Example fix

// before
bd init --server-user "$DB_USER"  # DB_USER empty
// after
export BEADS_DOLT_SERVER_USER=beads
bd init

Defensive patterns

Strategy: validation

Validate before calling

if [ -z "$SERVER_USER" ]; then echo "SERVER_USER empty; omitting flag"; unset SERVER_USER; fi

Try / catch

if err := cmd.Execute(); err != nil && strings.Contains(err.Error(), "--server-user cannot be empty") { /* set env or omit flag */ }

Prevention

Verify secret/user variables are populated before invoking bd
Use BEADS_DOLT_SERVER_USER instead of empty flag overrides
Fail fast in CI when required user vars are empty
Don't attempt to clear config with empty flag values

When it happens

Trigger: Running a command that promotes server flags with `--server-user ""` explicitly, typically from a script where the user variable is empty.

Common situations: Empty $DB_USER in CI pipelines; attempting to clear a previously configured user by passing an empty flag; templated deploy scripts with missing secrets.

Related errors

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