{"record":{"id":"c522daaa66378a97","repo":"kovidgoyal/kitty","slug":"ssh-controlmaster-not-functional-after-being-start","errorCode":null,"errorMessage":"SSH ControlMaster not functional after being started explicitly","messagePattern":"SSH ControlMaster not functional after being started explicitly","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kittens/ssh/main.go","lineNumber":728,"sourceCode":"\t\tc.Stdin, c.Stdout, c.Stderr = os.Stdin, os.Stdout, os.Stderr\n\t\terr := c.Run()\n\t\tif err != nil {\n\t\t\terr = fmt.Errorf(\"Failed to start SSH ControlMaster with cmdline: %s and error: %w\", strings.Join(cmcmd, \" \"), err)\n\t\t}\n\t\tmaster_checked = false\n\t\tmaster_is_alive = false\n\t\treturn err\n\t}\n\tif host_opts.Forward_remote_control && os.Getenv(\"KITTY_LISTEN_ON\") != \"\" {\n\t\tif !host_opts.Share_connections {\n\t\t\treturn 1, fmt.Errorf(\"Cannot use forward_remote_control=yes without share_connections=yes as it relies on SSH Controlmasters\")\n\t\t}\n\t\tif !master_is_functional() {\n\t\t\tif err = run_control_master(); err != nil {\n\t\t\t\treturn 1, err\n\t\t\t}\n\t\t\tif !master_is_functional() {\n\t\t\t\treturn 1, fmt.Errorf(\"SSH ControlMaster not functional after being started explicitly\")\n\t\t\t}\n\t\t}\n\t\tprotocol, listen_on, found := strings.Cut(os.Getenv(\"KITTY_LISTEN_ON\"), \":\")\n\t\tif !found {\n\t\t\treturn 1, fmt.Errorf(\"Invalid KITTY_LISTEN_ON: %#v\", os.Getenv(\"KITTY_LISTEN_ON\"))\n\t\t}\n\t\tif protocol == \"unix\" && strings.HasPrefix(listen_on, \"@\") {\n\t\t\treturn 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)\n\t\t}\n\t\tcmcmd := slices.Clone(cmd[:insertion_point])\n\t\tcmcmd = append(cmcmd, control_master_args...)\n\t\tcmcmd = append(cmcmd, \"-R\", \"0:\"+listen_on, \"-O\", \"forward\")\n\t\tcmcmd = append(cmcmd, \"--\", hostname)\n\t\tc := exec.Command(cmcmd[0], cmcmd[1:]...)\n\t\tb := bytes.Buffer{}\n\t\tc.Stdout = &b\n\t\tc.Stderr = os.Stderr\n\t\tif err := c.Run(); err != nil {","sourceCodeStart":710,"sourceCodeEnd":746,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kittens/ssh/main.go#L710-L746","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"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'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pre-create and keep the ControlPath directory writable","Avoid mixing manual ControlMaster settings with the kitten's","Periodically prune stale control sockets"],"tags":["kitty","ssh","controlmaster","multiplexing"],"backgroundTag":"ssh-controlmaster-failure","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}