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

Error message

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

What it means

resolveExplicitServerConnEnv validates the --server-host flag when the user explicitly sets it. An explicitly passed empty string is treated as a mistake rather than falling back to env/default, so it returns this error listing the fallback order (BEADS_DOLT_SERVER_HOST env var, then configfile.DefaultDoltServerHost). The point is to prevent flags from being silently ignored.

Source

Thrown at cmd/bd/init.go:3185

// resolveExplicitServerConnEnv turns the explicit --server-* flags into the
// set of environment changes promoteExplicitServerConnFlags will apply. It
// validates every flag before returning, so a later invalid flag cannot leave
// an earlier valid one already applied to the process environment.
//
// Because a socket outranks host/port everywhere downstream, selecting TCP
// explicitly (--server-host or --server-port) also clears an ambient
// BEADS_DOLT_SERVER_SOCKET unless --server-socket was itself given. An
// explicitly empty --server-socket clears the ambient socket too: empty is
// the documented "use TCP" value (see configfile.GetDoltServerSocket).
// Changed-but-empty host/user and out-of-range port values fail explicitly
// rather than being silently ignored.
func resolveExplicitServerConnEnv(cmd *cobra.Command) ([]serverConnEnvMutation, error) {
	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 {

View on GitHub (pinned to 71377f2769)

Solutions

Omit --server-host entirely to use BEADS_DOLT_SERVER_HOST or the built-in default
Export BEADS_DOLT_SERVER_HOST=<host> instead of passing an empty flag
Fix the wrapping script so the variable is non-empty before invoking bd

Example fix

// before
bd init --server-host ""
// after
bd init --server-host dolt.example.internal
# or simply omit the flag and set the env:
export BEADS_DOLT_SERVER_HOST=dolt.example.internal

Defensive patterns

Strategy: validation

Validate before calling

if [ -z "$SERVER_HOST" ]; then unset SERVER_HOST; fi  # don't pass empty vars to --server-host

Try / catch

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

Prevention

Only pass --server-host with a verified non-empty value
Prefer BEADS_DOLT_SERVER_HOST env over empty flag overrides
In scripts, guard: [ -n "$HOST_VAR" ] before building the command
Never use empty flag values to 'reset' configuration

When it happens

Trigger: Invoking any command that promotes server connection flags (via promoteExplicitServerConnFlags) with `--server-host ""` explicitly on the command line.

Common situations: Script variables that expand to empty (e.g. --server-host "$MY_HOST" with MY_HOST unset); copy-pasted examples with a blank value; attempting to 'unset' the host by passing an empty flag.

Related errors

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