What causes "--proxied-server-port must be between 1 and 65535, got %d" in gastownhall/beads?

Choose a port in 1–65535, avoiding privileged ports (<1024) unless running as root.

--proxied-server-port must be between 1 and 65535, got %d

Error message

--proxied-server-port must be between 1 and 65535, got %d

What it means

When `--proxied-server-port` is supplied, init bounds-checks it to the valid TCP port range 1–65535. Values outside that range cannot identify a TCP port and are rejected before anything is created (cmd/bd/init.go:484-486).

Source

Thrown at cmd/bd/init.go:485

			}
		}
		if serverRootPath != "" {
			if !initProxiedServer {
				return fmt.Errorf("--proxied-server-root-path requires --proxied-server")
			}
			if !filepath.IsAbs(serverRootPath) {
				return fmt.Errorf("--proxied-server-root-path must be an absolute path, got %q", serverRootPath)
			}
			if err := validateProxiedServerRootPath(serverRootPath); err != nil {
				return fmt.Errorf("--proxied-server-root-path %v", err)
			}
		}
		if serverProxyPort != 0 {
			if !initProxiedServer {
				return fmt.Errorf("--proxied-server-port requires --proxied-server")
			}
			if serverProxyPort < 1 || serverProxyPort > 65535 {
				return fmt.Errorf("--proxied-server-port must be between 1 and 65535, got %d", serverProxyPort)
			}
		}
		if idleTimeoutSet {
			if !initProxiedServer {
				return fmt.Errorf("--proxied-server-idle-timeout requires --proxied-server")
			}
			if serverProxyIdleTimeout < 0 {
				return fmt.Errorf("--proxied-server-idle-timeout must be 0 (never) or a positive duration, got %s", serverProxyIdleTimeout)
			}
			if serverProxyIdleTimeout == 0 {
				serverProxyIdleTimeout = proxy.IdleTimeoutNever
			}
		}

		externalProvided := externalHost != "" || externalPort != 0 || externalSocketPath != "" ||
			externalUser != "" ||
			externalTLS || externalTLSCACertPath != "" || externalTLSCertPath != "" || externalTLSKeyPath != "" ||
			externalTLSServerName != "" || externalTLSSkipVerify || externalKeepAlive != 0

View on GitHub (pinned to 71377f2769)

Solutions

Choose a port in 1–65535, avoiding privileged ports (<1024) unless running as root.
If you wanted an ephemeral/OS-assigned port, omit the flag instead of passing 0.
Check the wrapper script or env interpolation that produced the bad value.

Example fix

// before
bd init --proxied-server --proxied-server-port 70000
// after
bd init --proxied-server --proxied-server-port 8165

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
if [[ -n "$PROXY_PORT" ]]; then
  if ! [[ "$PROXY_PORT" =~ ^[0-9]+$ ]] || (( PROXY_PORT < 1 || PROXY_PORT > 65535 )); then
    echo "port must be 1-65535, got $PROXY_PORT" >&2; exit 2
  fi
fi

Type guard

func validProxyPort(p int) bool { return p >= 1 && p <= 65535 }

Try / catch

if out, err := exec.Command("bd", "init", args...).CombinedOutput(); err != nil {
    if strings.Contains(string(out), "must be between 1 and 65535") {
        // fix the port value and retry
    }
}

Prevention

Range-check ports in wrapper scripts before invoking CLI tools.
Don't pass 0 expecting OS-assigned ports; omit the flag instead.
Validate that interpolated env vars produce plain integers.

When it happens

Trigger: Running `bd init --proxied-server --proxied-server-port 0` or `--proxied-server-port 70000` — any serverProxyPort < 1 or > 65535. Note 0 is treated as "flag not set" upstream, so explicitly passing 0 also fails here.

Common situations: Off-by-one from using port 0 expecting OS-assigned ports (unsupported here); pasting an erroneous port from a config (e.g. 655360); string-to-int conversion bugs in wrapper scripts producing garbage numbers.

Related errors

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