kovidgoyal/kitty · error · KeyError

unknown option -- {arg[1:]}

Error message

unknown option -- {arg[1:]}

What it means

set_server_args_in_cmdline() rebuilds an ssh command line by matching each option against a table of known ssh options (that specify whether it takes a value, is a flag, etc.). When an argument starting with '-' isn't found in the table, it raises KeyError(f'unknown option -- {arg[1:]}') — the KeyError message text is the unknown ssh option name. It is called via modify_argv_for_launch_with_cwd() when the ssh kitten prepares to launch ssh.

Source

Thrown at kittens/ssh/utils.py:305

                        expecting_extra_val = matching_ex
                        expecting_option_val = True
                    continue
            # could be a multi-character option
            all_args = argument[1:]
            for i, arg in enumerate(all_args):
                arg = f'-{arg}'
                if arg in boolean_ssh_args:
                    ssh_args.append(arg)
                    continue
                if arg in other_ssh_args:
                    ssh_args.append(arg)
                    rest = all_args[i + 1 :]
                    if rest:
                        ssh_args.append(rest)
                    else:
                        expecting_option_val = True
                    break
                raise KeyError(f'unknown option -- {arg[1:]}')
            continue
        if expecting_option_val:
            if expecting_extra_val:
                found_extra_args.extend((expecting_extra_val, argument))
                expecting_extra_val = ''
            else:
                ssh_args.append(argument)
            expecting_option_val = False
            continue
        del ans[i + 1 :]
        if allocate_tty and ans[i] != '-t':
            ans.insert(i, '-t')
        break
    argv[:] = ans + server_args


def get_connection_data(args: list[str], cwd: str = '', extra_args: tuple[str, ...] = ()) -> SSHConnectionData | None:
    boolean_ssh_args, other_ssh_args = get_ssh_cli()

View on GitHub (pinned to 6d5d0c4406)

Solutions

  1. Update kitty to the latest version — new ssh options are regularly added to its option table.
  2. Remove/avoid the unrecognized ssh option on the kitten ssh command line (put exotic options in ~/.ssh/config instead of argv).
  3. If the option must stay and you're on latest kitty, report it upstream so the table gains the option; as a local patch add it to the option table in kittens/ssh/utils.py.
  4. Check for typos/malformed dashes in the ssh invocation.

Example fix

# before
kitten ssh -O forward user@host  # KeyError: unknown option -- O (if unknown to kitty's table)

# after
# move it into ~/.ssh/config or update kitty
kitten ssh user@host
Defensive patterns

Strategy: try-catch

Validate before calling

import kittens.ssh.utils as u

def safe_set_server_args(cmdline: list[str]) -> list[str]:
    args = [a for a in cmdline if not (a.startswith('-') and a.lstrip('-') not in KNOWN_OPTS)]
    return u.set_server_args_in_cmdline(args)  # pre-filter unknown options

Try / catch

try:
    set_server_args_in_cmdline(cmdline)
except KeyError as e:
    bad = e.args[0]  # e.g. 'unknown option -- XYZ'
    # drop the offending option (and its value) and retry, or fall back to plain ssh
    subprocess.call(['ssh', *cmdline])

Prevention

When it happens

Trigger: Passing an ssh command line containing an option kitty's option table doesn't know — typically new/obscure ssh flags (`-O`, newer OpenSSH options, vendor-specific flags), or a malformed arg like `-` followed by unexpected text. The loop consumes the table entry's value or sets expecting_option_val; no entry means KeyError.

Common situations: Using a newer OpenSSH client with options kitty hasn't catalogued in this version; passing through unusual options in SSH config aliases expanded onto the command line; typos like `-pOrt` or concatenated short options that kitty's parser can't split; running an older kitty with a newer system ssh.

Related errors

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