{"record":{"id":"eacbceb0d0cbcbb4","repo":"kovidgoyal/kitty","slug":"cannot-forward-kitty-remote-control-socket-when-an","errorCode":null,"errorMessage":"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","messagePattern":"Cannot forward kitty remote control socket when an abstract UNIX socket \\((.+?)\\) is used, due to limitations in OpenSSH\\. Use either a path based one or a TCP socket","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kittens/ssh/main.go","lineNumber":736,"sourceCode":"\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 {\n\t\t\treturn 1, fmt.Errorf(\"%s\\nSetup of port forward in SSH ControlMaster failed with error: %w\", b.String(), err)\n\t\t}\n\t\tport, err := strconv.Atoi(strings.TrimSpace(b.String()))\n\t\tif err != nil {\n\t\t\tos.Stderr.Write(b.Bytes())\n\t\t\treturn 1, fmt.Errorf(\"Setup of port forward in SSH ControlMaster failed with error: invalid resolved port returned: %s\", b.String())\n\t\t}\n\t\tcd.listen_on = \"tcp:localhost:\" + strconv.Itoa(port)","sourceCodeStart":718,"sourceCodeEnd":754,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kittens/ssh/main.go#L718-L754","documentation":"KITTY_LISTEN_ON uses an abstract UNIX socket (address starting with '@'). OpenSSH's remote forward (-R) cannot bind abstract sockets, so kitty cannot forward remote control in this setup.","triggerScenarios":"kitty started with --listen-on 'unix:@kitty' (abstract namespace socket) and the SSH kitten run with forward_remote_control=yes.","commonSituations":"Linux systems using abstract sockets to avoid leftover socket files; distro configs or tutorials recommending unix:@ names.","solutions":["Restart kitty with a path-based socket: kitty --listen-on unix:/tmp/kitty-socket","Or use a TCP listen socket: kitty --listen-on tcp:localhost:0","Or disable forward_remote_control"],"exampleFix":"# before\nkitty --listen-on unix:@mykitty\n\n# after\nkitty --listen-on unix:/tmp/mykitty.sock","handlingStrategy":"validation","validationCode":"case \"$KITTY_LISTEN_ON\" in unix:@*) echo 'abstract socket cannot be forwarded'; exit 1;; esac","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Start kitty with a path-based or TCP listen socket if you use remote control over ssh","Avoid unix:@ listen-on when using forward_remote_control"],"tags":["kitty","ssh","unix-socket","openssh-limitation"],"backgroundTag":"abstract-unix-socket-unsupported","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}