kovidgoyal/kitty · error

Cannot use forward_remote_control=yes without share_connecti

Error message

Cannot use forward_remote_control=yes without share_connections=yes as it relies on SSH Controlmasters

What it means

Thrown by the kitty SSH kitten when forward_remote_control=yes is set in the SSH kitten config but share_connections is not enabled. Forwarding kitty's remote control socket to the remote host is implemented via SSH ControlMaster multiplexing, so it cannot work without it.

Source

Thrown at kittens/ssh/main.go:721

	}
	run_control_master := func() error {
		cmcmd := slices.Clone(cmd[:insertion_point])
		cmcmd = append(cmcmd, control_master_args...)
		cmcmd = append(cmcmd, "-N", "-f")
		cmcmd = append(cmcmd, "--", hostname)
		c := exec.Command(cmcmd[0], cmcmd[1:]...)
		c.Stdin, c.Stdout, c.Stderr = os.Stdin, os.Stdout, os.Stderr
		err := c.Run()
		if err != nil {
			err = fmt.Errorf("Failed to start SSH ControlMaster with cmdline: %s and error: %w", strings.Join(cmcmd, " "), err)
		}
		master_checked = false
		master_is_alive = false
		return err
	}
	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...)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Set share_connections=yes in the SSH kitten config (kitty.conf ssh config or ~/.config/kitty/ssh.conf)
2. Alternatively remove forward_remote_control=yes if you don't need remote control on the remote host

Example fix

# before
forward_remote_control yes
share_connections no

# after
forward_remote_control yes
share_connections yes

# in ssh.conf / kitty.conf, verify before running:
grep -E 'forward_remote_control\s+yes' ~/.config/kitty/ssh.conf && \
  grep -E 'share_connections\s+yes' ~/.config/kitty/ssh.conf || echo 'must enable share_connections'

When it happens

Trigger: Running kitty's ssh kitten with forward_remote_control=yes while share_connections is unset/no (the default) in kitty.conf or the ssh kitten config file, while KITTY_LISTEN_ON is set.

Common situations: Enabling remote control forwarding to use kitty remote control commands over SSH without also turning on connection sharing; overriding share_connections=no in a per-host config block.

Related errors

• Passwords are not allowed to start with hyphens, ignoring th
• Invalid KITTY_LISTEN_ON: %#v
• Bad config lines: %s with error: %s
• Too few arguments to remote_control function
• Too few arguments to remote_control_script function

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