--addr %q: port must be a number from 0 to 65535 (0 picks an

Error message

--addr %q: port must be a number from 0 to 65535 (0 picks an ephemeral port)

What it means

ValidateBindAddr parses a --addr value as HOST:PORT with a numeric IP host. This error is thrown when the port portion is not a valid unsigned integer in the uint16 range (0-65535). Port 0 is explicitly allowed and picks an ephemeral port.

Source

Thrown at internal/httpapi/server.go:444

	connCapWarned atomic.Bool
}

// ValidateBindAddr enforces the bind posture, following the policy the managed
// Dolt child already lives under (validateManagedServerConfigPolicy in
// cmd/bd/proxied_server.go): the host must be a NUMERIC IP literal.
//
// Hostnames are refused, "localhost" included. A name is not a listener
// specification — it resolves to whatever the host's resolver says today, so
// the operator cannot tell from the flag which interfaces they just opened.
// Unix sockets are not supported at all; they fail here because they do not
// parse as host:port.
func ValidateBindAddr(addr string, allowNonLoopback bool) (net.IP, error) {
	host, port, err := net.SplitHostPort(addr)
	if err != nil {
		return nil, fmt.Errorf("--addr %q must be HOST:PORT with a numeric IP literal host (unix sockets are not supported): %w", addr, err)
	}
	if _, err := strconv.ParseUint(port, 10, 16); err != nil {
		return nil, fmt.Errorf("--addr %q: port must be a number from 0 to 65535 (0 picks an ephemeral port)", addr)
	}
	ip := net.ParseIP(host)
	if ip == nil {
		return nil, fmt.Errorf("--addr %q: host must be a numeric IP literal, not a name — use 127.0.0.1 rather than localhost", addr)
	}
	if !ip.IsLoopback() && !allowNonLoopback {
		return nil, fmt.Errorf("--addr %q binds beyond loopback, which requires --allow-non-loopback (and, with it, --auth-token-file)", addr)
	}
	return ip, nil
}

// Listen validates the configuration, binds the listener, and reports the
// bound address on stdout and the startup state on stderr. It does not accept
// anything until Serve runs.
//
// There is no lock file, pid file or discovery file: bd serve is
// operator-invoked and the TCP bind IS the mutual exclusion, so a second
// instance on the same fixed port fails here with the operating system's own

View on GitHub (pinned to 71377f2769)

Solutions

Use a numeric port between 0 and 65535, e.g. --addr 127.0.0.1:8080 (0 for ephemeral)
Strip whitespace/quotes/paths from the addr value before passing it
Look up the numeric port behind any service name and use the number instead

Example fix

// before
srv, err := httpapi.Listen(cfg with Addr: "127.0.0.1:http")
// after
srv, err := httpapi.Listen(cfg with Addr: "127.0.0.1:80")

Defensive patterns

Strategy: validation

Validate before calling

func validPort(addr string) bool {
    _, port, err := net.SplitHostPort(addr)
    if err != nil { return false }
    n, err := strconv.ParseUint(port, 10, 16)
    return err == nil && n <= 65535
}

Try / catch

if err := validateAddr(addr); err != nil {
    var ve *strconv.NumError
    if errors.As(err, &ve) { /* handle bad port */ }
}

Prevention

Always use numeric ports, never service names
Use port 0 when any free port is acceptable
Trim config/env values before passing to --addr

When it happens

Trigger: Calling ValidateBindAddr (or starting the httpapi server) with an addr whose port fails strconv.ParseUint(port, 10, 16): non-numeric port like '127.0.0.1:http' or '127.0.0.1:abc', a service name instead of a number, or a value with surrounding characters like '127.0.0.1:8080 ' or sign/plus prefixes.

Common situations: Operator pastes a URL-form address (127.0.0.1:8080/ with path junk), uses a named service port ('http'), includes stray whitespace or quotes from a config file, or typos the port digits.

Related errors

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