What causes "invalid listen port: %s" in junegunn/fzf?

Use a numeric port in 0-65535, e.g. --listen=localhost:6266

invalid listen port: %s

Error message

invalid listen port: %s

What it means

The host:port in --listen was structurally valid, but the port component failed strconv.Atoi or fell outside 0-65535. Port 0 is allowed and asks the kernel for an ephemeral port; anything non-numeric, negative, or above 65535 is rejected.

Source

Thrown at src/server.go:73

var defaultListenAddr = listenAddress{"localhost", 0, ""}

func parseListenAddress(address string) (listenAddress, error) {
	if strings.HasSuffix(address, ".sock") {
		return listenAddress{"", 0, address}, nil
	}

	parts := strings.SplitN(address, ":", 3)
	if len(parts) == 1 {
		parts = []string{"localhost", parts[0]}
	}
	if len(parts) != 2 {
		return defaultListenAddr, fmt.Errorf("invalid listen address: %s", address)
	}
	portStr := parts[len(parts)-1]
	port, err := strconv.Atoi(portStr)
	if err != nil || port < 0 || port > 65535 {
		return defaultListenAddr, fmt.Errorf("invalid listen port: %s", portStr)
	}
	if len(parts[0]) == 0 {
		parts[0] = "localhost"
	}
	return listenAddress{parts[0], port, ""}, nil
}

func startHttpServer(address listenAddress, actionChannel chan []*action, getHandler func(getParams) string) (net.Listener, int, error) {
	host := address.host
	port := address.port
	apiKey := os.Getenv("FZF_API_KEY")
	if !address.IsLocal() && len(apiKey) == 0 {
		return nil, port, errors.New("FZF_API_KEY is required to allow remote access")
	}

	var listener net.Listener
	var err error
	if len(address.sock) > 0 {

View on GitHub (pinned to bd4efa277b)

Solutions

Use a numeric port in 0-65535, e.g. --listen=localhost:6266
Pick an unused port for a fixed listener; fzf also prints the chosen port when 0 is used
Check for stray characters after the port

Example fix

# before
fzf --listen=localhost:99999
# after
fzf --listen=localhost:6266

Defensive patterns

Strategy: validation

Validate before calling

# validate the port component in shell
port="${ADDR##*:}"
case "$port" in
  ''|*[!0-9]*) echo "bad port: $port" >&2; exit 1;;
esac
[ "$port" -le 65535 ] || { echo "port out of range: $port" >&2; exit 1; }

Prevention

Use numeric ports only; service names like http are not supported
Double-check for trailing path or query text glued onto the port

When it happens

Trigger: Passing --listen=localhost:99999, --listen=localhost:-1, --listen=localhost:6266x, or a service name ('localhost:http') instead of a number.

Common situations: Off-by-one typos in port numbers; copying URLs where the port got concatenated with a path ('6266/api'); using named services instead of numeric ports.

Related errors

AI-assisted analysis of junegunn/fzf@bd4efa277b (2026-08-15). Data as JSON: /api/errors/1f12fd50dbb48e45. Report an issue: GitHub.