%s\nSetup of port forward in SSH ControlMaster failed with e

Error message

%s\nSetup of port forward in SSH ControlMaster failed with error: %w

What it means

The kitten runs ssh -R 0:<listen_on> -O forward against the ControlMaster to create a remote forward for remote control; if the ssh command itself errors, the captured stdout and the underlying error are wrapped in this message.

Source

Thrown at kittens/ssh/main.go:747

			}
		}
		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)
	}
	term, err := tty.OpenControllingTerm(tty.SetNoEcho)
	if err != nil {
		return 1, fmt.Errorf("Failed to open controlling terminal with error: %w", err)
	}
	cd.echo_on = term.WasEchoOnOriginally()
	cd.host_opts, cd.literal_env = host_opts, literal_env
	cd.request_data = need_to_request_data
	cd.hostname_for_match, cd.username = hostname_for_match, uname
	escape_codes_to_set_colors, err := change_colors(cd.host_opts.Color_scheme)
	if err == nil {

View on GitHub (pinned to 6d5d0c4406)

Solutions

Re-run once — transient master death is common; then increase ControlPersist timeout
Check server sshd_config allows forwarding (AllowTcpForwarding yes)
Run ssh -O forward -R 0:<socket> manually against the master to see the raw ssh error
Verify network connectivity to the host

Defensive patterns

Strategy: retry

Prevention

Keep ControlPersist long enough to survive session setup
Ensure sshd allows TCP forwarding on the remote host
Retry once on master-died errors before investigating

When it happens

Trigger: exec of ssh -O forward fails (non-zero exit) — network down, master died between check and use, ssh refuses the -R forward, remote sshd forbids port forwarding.

Common situations: Server has AllowTcpForwarding no / DisableForwarding; connection dropped mid-setup; ControlMaster expired (ControlPersist timeout) between the functional check and the forward command.

Related errors

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