junegunn/fzf · error

failed to listen on %s

Error message

failed to listen on %s

What it means

Error "failed to listen on %s" thrown in junegunn/fzf.

Source

Thrown at src/server.go:102

	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 {
		if _, err := os.Stat(address.sock); err == nil {
			// Check if the socket is already in use
			if conn, err := net.Dial("unix", address.sock); err == nil {
				conn.Close()
				return nil, 0, fmt.Errorf("socket already in use: %s", address.sock)
			}
			os.Remove(address.sock)
		}
		listener, err = net.Listen("unix", address.sock)
		if err != nil {
			return nil, 0, fmt.Errorf("failed to listen on %s", address.sock)
		}
		os.Chmod(address.sock, 0600)
	} else {
		addrStr := fmt.Sprintf("%s:%d", host, port)
		listener, err = net.Listen("tcp", addrStr)
		if err != nil {
			return nil, port, fmt.Errorf("failed to listen on %s", addrStr)
		}
		if port == 0 {
			addr := listener.Addr().String()
			parts := strings.Split(addr, ":")
			if len(parts) < 2 {
				return nil, port, fmt.Errorf("cannot extract port: %s", addr)
			}
			var err error
			port, err = strconv.Atoi(parts[len(parts)-1])
			if err != nil {
				return nil, port, err

View on GitHub (pinned to bd4efa277b)

Solutions

1. Check that the parent directory of the socket path exists and is writable
2. Verify permissions on the socket path (fzf chmods it to 0600)
3. For TCP, choose a port that is not already in use and that the user is allowed to bind (ports <1024 need privileges)

When it happens

Trigger: Thrown at src/server.go:102 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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