SSH ControlMaster not functional after being started explici

Error message

SSH ControlMaster not functional after being started explicitly

What it means

After the SSH kitten explicitly starts an SSH ControlMaster (via ssh -O / ControlMaster setup), it checks the master socket is functional; if the check fails immediately after a successful start, this error is returned. It indicates ssh could not create or use the control socket despite exiting without error.

Source

Thrown at kittens/ssh/main.go:728

		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...)
		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 {

View on GitHub (pinned to 6d5d0c4406)

Solutions

Run ssh -vvv manually with the same ControlMaster options to see why the master socket fails
Check the ControlPath directory exists and is writable (e.g. ~/.ssh/ or a TMPDIR that supports unix sockets)
Disable conflicting ssh_config ControlMaster/Multiplexing overrides and let the kitten manage it
Upgrade OpenSSH client if it's very old

Defensive patterns

Strategy: fallback

Validate before calling

ssh -o ControlMaster=auto -o ControlPath=~/.ssh/cm-%r@%h:%p -O check host 2>&1 | grep -q 'Master running' && echo ok || echo 'master broken'

Prevention

Pre-create and keep the ControlPath directory writable
Avoid mixing manual ControlMaster settings with the kitten's
Periodically prune stale control sockets

When it happens

Trigger: forward_remote_control enabled, master_is_functional() false, run_control_master() succeeds, but the control socket still doesn't respond (broken ssh multiplexing, unwritable ControlPath directory, odd ssh version).

Common situations: ControlPath pointing to a directory that doesn't exist or isn't writable; ssh client too old/new with incompatible multiplexing; SELinux/AppArmor blocking the socket; stale ssh-agent environment.

Related errors

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