--server-port must be between 1 and 65535, got %d; omit the

Error message

--server-port must be between 1 and 65535, got %d; omit the flag to use BEADS_DOLT_SERVER_PORT or the default (%d)

What it means

resolveExplicitServerConnEnv validates the --server-port flag range when explicitly provided. Ports below 1 or above 65535 are invalid TCP ports and produce this error, which also hints that omitting the flag falls back to BEADS_DOLT_SERVER_PORT or configfile.DefaultDoltServerPort. The invalid value is echoed in the message via %d.

Source

Thrown at cmd/bd/init.go:3192

// 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 {
	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})
		}

View on GitHub (pinned to 71377f2769)

Solutions

Pass a valid port between 1 and 65535
Omit --server-port to use BEADS_DOLT_SERVER_PORT or the default
Fix the variable feeding the flag so it evaluates to a valid port

Example fix

// before
bd init --server-port 70000
// after
bd init --server-port 3307
# or omit and use env:
export BEADS_DOLT_SERVER_PORT=3307

Defensive patterns

Strategy: validation

Validate before calling

if ! (( PORT >= 1 && PORT <= 65535 )); then echo "invalid port: $PORT" >&2; exit 1; fi

Try / catch

if err := cmd.Execute(); err != nil && strings.Contains(err.Error(), "--server-port must be between 1 and 65535") { /* fix port */ }

Prevention

Validate port variables before interpolation into CLI flags
Remember valid TCP ports are 1-65535
Don't paste host:port pairs into the port flag
Use env BEADS_DOLT_SERVER_PORT for defaults instead of computed flags

When it happens

Trigger: Running a command that promotes server flags with `--server-port 0`, `--server-port 70000`, a negative number, or a non-numeric value that cobra's GetInt coerced/defaulted oddly.

Common situations: Typos like --server-port 655536; shell expansion of an empty/unset variable to 0; copying a host:port pair wholesale into the port flag; range-boundary confusion.

Related errors

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