{"record":{"id":"5af9791b86f06dff","repo":"kovidgoyal/kitty","slug":"failed-to-start-ssh-controlmaster-with-cmdline-s","errorCode":null,"errorMessage":"Failed to start SSH ControlMaster with cmdline: %s and error: %w","messagePattern":"Failed to start SSH ControlMaster with cmdline: (.+?) and error: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kittens/ssh/main.go","lineNumber":713,"sourceCode":"\t\t// slices.Insert can mutate cmd's backing array in place; clone so cmd stays intact\n\t\tcheck_cmd := slices.Insert(slices.Clone(cmd), 1, \"-O\", \"check\")\n\t\tmaster_is_alive = exec.Command(check_cmd[0], check_cmd[1:]...).Run() == nil\n\t\treturn master_is_alive\n\t}\n\n\tif need_to_request_data && host_opts.Share_connections && master_is_functional() {\n\t\tneed_to_request_data = false\n\t}\n\trun_control_master := func() error {\n\t\tcmcmd := slices.Clone(cmd[:insertion_point])\n\t\tcmcmd = append(cmcmd, control_master_args...)\n\t\tcmcmd = append(cmcmd, \"-N\", \"-f\")\n\t\tcmcmd = append(cmcmd, \"--\", hostname)\n\t\tc := exec.Command(cmcmd[0], cmcmd[1:]...)\n\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\"), \":\")","sourceCodeStart":695,"sourceCodeEnd":731,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kittens/ssh/main.go#L695-L731","documentation":"When a shared connection is requested but no live ControlMaster exists, the kitten execs 'ssh -N -f ...' to start one; c.Run() failed (non-zero exit or spawn failure). The full command line and the underlying error are wrapped in this message.","triggerScenarios":"The master bootstrap ssh process failing: authentication failure (no keys/agent), unknown hostname, ssh config errors, ControlPath directory uncreatable, or the ssh binary itself erroring under -N -f.","commonSituations":"First connection to a host without valid credentials; ControlPath pointing to a non-existent directory with no auto-create; sshd refusing ControlMaster; ProxyCommand failing; ssh versions disallowing -f combos; too many stale master sockets exhausting the multiplex dir.","solutions":["Reproduce manually with the cmdline from the error message (without -f) to see ssh's real error","Verify auth works: ssh -o ControlPath=none user@host true","Check ControlPath in ssh_config — use a directory that exists (%C-style paths auto-create in newer OpenSSH)","Clear stale sockets: rm -rf ~/.local/share/kitty/ssh-control-master/* or your ControlPath dir","Disable share_connections for the problematic host as a workaround"],"exampleFix":"# before: kitty.conf has share_connections yes, master fails\n# debug manually:\nssh -vvv -o ControlPath='/tmp/%r@%h:%p' -N user@host\n# after: fix ControlPath to an existing dir\nHost *\n  ControlPath ~/.local/share/kitty/cm-%C\nmkdir -p ~/.local/share/kitty","handlingStrategy":"retry","validationCode":"// pre-flight the master manually:\n// ssh -o ControlPath=<path> -N -f user@host || handle auth/config issue first","typeGuard":null,"tryCatchPattern":"if err := startControlMaster(cmcmd); err != nil {\n    if strings.Contains(err.Error(), \"Failed to start SSH ControlMaster\") {\n        // retry once without -f to capture the real ssh error, then surface it\n    }\n}","preventionTips":["Validate ssh auth works before enabling share_connections","Keep ControlPath inside an existing directory","Periodically clear stale master sockets","Retry once on master start failure before giving up"],"tags":["ssh-kitten","controlmaster","connection-sharing","ssh"],"backgroundTag":"ssh-control-master-start-failure","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}