Setup of port forward in SSH ControlMaster failed with error

Error message

Setup of port forward in SSH ControlMaster failed with error: invalid resolved port returned: %s

What it means

After a successful ssh -R 0:... -O forward, ssh is expected to print the dynamically allocated listening port on stdout. strconv.Atoi on that output failed, meaning ssh printed something that isn't a number (or nothing).

Source

Thrown at kittens/ssh/main.go:752

		}
		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 {
		err = term.WriteAllString(escape_codes_to_set_colors + loop.SAVE_PRIVATE_MODE_VALUES + loop.PUSH_KEY_FLAGS + loop.HANDLE_TERMIOS_SIGNALS.EscapeCodeToSet())
	}
	if err != nil {
		return 1, err
	}

View on GitHub (pinned to 6d5d0c4406)

Solutions

Check OpenSSH client version; upgrade to a modern version (>= 7.6, ideally 8+)
Ensure no wrapper script/banner writes extra text to ssh stdout
Reproduce manually: ssh -O forward -R 0:<socket> <host> and inspect what is printed

Defensive patterns

Strategy: fallback

Validate before calling

ssh -V 2>&1  # require OpenSSH >= 7.6 before enabling forward_remote_control

Prevention

Use a recent OpenSSH client
Don't wrap ssh in scripts that print to stdout

When it happens

Trigger: ssh -O forward succeeds (exit 0) but stdout is empty or non-numeric — older OpenSSH versions that don't report the allocated port, or extra output polluting stdout.

Common situations: Very old OpenSSH clients (< 7.x) lacking '-R 0' port reporting; ssh wrappers or banners writing to stdout; patched/distrowrapped ssh binaries.

Related errors

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