kovidgoyal/kitty · error

Invalid KITTY_LISTEN_ON: %#v

Error message

Invalid KITTY_LISTEN_ON: %#v

What it means

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.

Source

Thrown at kittens/ssh/main.go:733

		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 {
			return 1, fmt.Errorf("%s\nSetup of port forward in SSH ControlMaster failed with error: %w", b.String(), err)
		}
		port, err := strconv.Atoi(strings.TrimSpace(b.String()))
		if err != nil {
			os.Stderr.Write(b.Bytes())

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Set KITTY_LISTEN_ON in the documented format: unix:/path/to/socket or tcp:PORT
2. Or unset it / drop forward_remote_control so the kitten doesn't try to forward it

Example fix

# before
export KITTY_LISTEN_ON=1234

# after
export KITTY_LISTEN_ON=tcp:1234

case "$KITTY_LISTEN_ON" in *:*) ;; *) echo "KITTY_LISTEN_ON must be protocol:address"; exit 1;; esac

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Password usage requested but KITTY_PUBLIC_KEY environment va
• Cannot use forward_remote_control=yes without share_connecti
• This should be run as kitten icat
• This should be run as `kitten notify ...`
• This should be run as kitten ssh

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