Cannot forward kitty remote control socket when an abstract

Error message

Cannot forward kitty remote control socket when an abstract UNIX socket (%s) is used, due to limitations in OpenSSH. Use either a path based one or a TCP socket

What it means

KITTY_LISTEN_ON uses an abstract UNIX socket (address starting with '@'). OpenSSH's remote forward (-R) cannot bind abstract sockets, so kitty cannot forward remote control in this setup.

Source

Thrown at kittens/ssh/main.go:736

	}
	if host_opts.Forward_remote_control && os.Getenv("KITTY_LISTEN_ON") != "" {
		if !host_opts.Share_connections {
			return 1, fmt.Errorf("Cannot use forward_remote_control=yes without share_connections=yes as it relies on SSH Controlmasters")
		}
		if !master_is_functional() {
			if err = run_control_master(); err != nil {
				return 1, err
			}
			if !master_is_functional() {
				return 1, fmt.Errorf("SSH ControlMaster not functional after being started explicitly")
			}
		}
		protocol, listen_on, found := strings.Cut(os.Getenv("KITTY_LISTEN_ON"), ":")
		if !found {
			return 1, fmt.Errorf("Invalid KITTY_LISTEN_ON: %#v", os.Getenv("KITTY_LISTEN_ON"))
		}
		if protocol == "unix" && strings.HasPrefix(listen_on, "@") {
			return 1, fmt.Errorf("Cannot forward kitty remote control socket when an abstract UNIX socket (%s) is used, due to limitations in OpenSSH. Use either a path based one or a TCP socket", listen_on)
		}
		cmcmd := slices.Clone(cmd[:insertion_point])
		cmcmd = append(cmcmd, control_master_args...)
		cmcmd = append(cmcmd, "-R", "0:"+listen_on, "-O", "forward")
		cmcmd = append(cmcmd, "--", hostname)
		c := exec.Command(cmcmd[0], cmcmd[1:]...)
		b := bytes.Buffer{}
		c.Stdout = &b
		c.Stderr = os.Stderr
		if err := c.Run(); err != nil {
			return 1, fmt.Errorf("%s\nSetup of port forward in SSH ControlMaster failed with error: %w", b.String(), err)
		}
		port, err := strconv.Atoi(strings.TrimSpace(b.String()))
		if err != nil {
			os.Stderr.Write(b.Bytes())
			return 1, fmt.Errorf("Setup of port forward in SSH ControlMaster failed with error: invalid resolved port returned: %s", b.String())
		}
		cd.listen_on = "tcp:localhost:" + strconv.Itoa(port)

View on GitHub (pinned to 6d5d0c4406)

Solutions

Restart kitty with a path-based socket: kitty --listen-on unix:/tmp/kitty-socket
Or use a TCP listen socket: kitty --listen-on tcp:localhost:0
Or disable forward_remote_control

Example fix

# before
kitty --listen-on unix:@mykitty

# after
kitty --listen-on unix:/tmp/mykitty.sock

Defensive patterns

Strategy: validation

Validate before calling

case "$KITTY_LISTEN_ON" in unix:@*) echo 'abstract socket cannot be forwarded'; exit 1;; esac

Prevention

Start kitty with a path-based or TCP listen socket if you use remote control over ssh
Avoid unix:@ listen-on when using forward_remote_control

When it happens

Trigger: kitty started with --listen-on 'unix:@kitty' (abstract namespace socket) and the SSH kitten run with forward_remote_control=yes.

Common situations: Linux systems using abstract sockets to avoid leftover socket files; distro configs or tutorials recommending unix:@ names.

Related errors

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/eacbceb0d0cbcbb4. Report an issue: GitHub.