{"record":{"id":"e27e8645e5753a24","repo":"kovidgoyal/kitty","slug":"invalid-kitty-listen-on-v","errorCode":null,"errorMessage":"Invalid KITTY_LISTEN_ON: %#v","messagePattern":"Invalid KITTY_LISTEN_ON: %#v","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kittens/ssh/main.go","lineNumber":733,"sourceCode":"\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 {\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())","sourceCodeStart":715,"sourceCodeEnd":751,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kittens/ssh/main.go#L715-L751","documentation":"The KITTY_LISTEN_ON environment variable must be of the form protocol:address (e.g. unix:/path/to/socket or tcp:port). strings.Cut on ':' found no separator, so the value is malformed and cannot be parsed to forward remote control.","triggerScenarios":"KITTY_LISTEN_ON set to a value without a colon (e.g. '1234' or 'socket'), reached only when forward_remote_control=yes and a functional ControlMaster exist.","commonSituations":"User manually sets KITTY_LISTEN_ON in the environment or wrapper script with a wrong format; kitty started with --listen-on in a nonstandard/invalid way.","solutions":["Set KITTY_LISTEN_ON in the documented format: unix:/path/to/socket or tcp:PORT","Or unset it / drop forward_remote_control so the kitten doesn't try to forward it"],"exampleFix":"# before\nexport KITTY_LISTEN_ON=1234\n\n# after\nexport KITTY_LISTEN_ON=tcp:1234","handlingStrategy":"validation","validationCode":"case \"$KITTY_LISTEN_ON\" in *:*) ;; *) echo \"KITTY_LISTEN_ON must be protocol:address\"; exit 1;; esac","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never set KITTY_LISTEN_ON manually; let kitty set it","If wrapping kitty, preserve its env vars verbatim"],"tags":["kitty","ssh","env-var","remote-control"],"backgroundTag":"invalid-environment-variable-format","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}