junegunn/fzf · error

invalid listen address: %s

Error message

invalid listen address: %s

What it means

The --listen address could not be parsed. parseListenAddress accepts '<port>', '<host>:<port>', or a path ending in '.sock'; anything that splits into something other than exactly 2 host/port parts (after a max-3 SplitN) is rejected as an invalid listen address.

Source

Thrown at src/server.go:68

}

func (addr listenAddress) IsLocal() bool {
	return addr.host == "localhost" || addr.host == "127.0.0.1" || len(addr.sock) > 0
}

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")

View on GitHub (pinned to bd4efa277b)

Solutions

1. Use the simple forms: --listen, --listen=6266, --listen=localhost:6266, or --listen=/path/server.sock
2. For IPv6, rely on 'localhost' resolution rather than a raw literal, or ensure bracketed forms supported by your fzf version
3. Do not include a scheme; strip http:// before passing

Example fix

# before
fzf --listen=http://0.0.0.0:6266
# after
fzf --listen=0.0.0.0:6266

# validate before passing to --listen
valid_listen() {
  case "$1" in
    *.sock|[0-9]*|""|localhost:[0-9]*|127.0.0.1:[0-9]*|\[*\]:[0-9]*) return 0;;
    *:*) printf '%s' "$1" | grep -Eq '^[^:]+:[0-9]+$' && return 0;;
  esac
  return 1
}
valid_listen "$ADDR" || { echo "bad listen address: $ADDR" >&2; exit 1; }

When it happens

Trigger: Passing --listen with more than one colon and a non-socket value, e.g. 'a:b:c', or an empty address that is not a .sock path; IPv6 literals like '::1:6266' also split wrong because SplitN on ':' produces 3 parts.

Common situations: Using IPv6 addresses without bracket notation; typos like '--listen=:6266:extra'; passing URLs ('http://localhost:6266') instead of host:port.

Related errors

• invalid listen port: %s
• permission denied: ${path}
• invalid popup option: ${arg} (expected: [center|top|bottom|l
• not a valid integer: ${str}
• invalid format: ${str}

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