kovidgoyal/kitty · error · ValueError

{argparse error from SystemExit}

Error message

{argparse error from SystemExit}

What it means

parse_launch_args wraps kitty's option parser; argparse errors normally exit the process, so the SystemExit is caught and re-raised as ValueError carrying argparse's message (e.g. unrecognized arguments, invalid choices).

Source

Thrown at kitty/launch.py:441

--hold-after-ssh
type=bool-set
When using :option:`--cwd`:code:`=current` or similar from a window that is running the ssh kitten,
the new window will run a local shell after disconnecting from the remote host, when this option
is specified.
"""


# }}}


def parse_launch_args(args: Sequence[str] | None = None) -> LaunchSpec:
    args = list(args or ())
    try:
        opts, args = parse_args(result_class=LaunchCLIOptions, args=args, ospec=options_spec)
    except SystemExit as e:
        raise ValueError(str(e)) from e
    return LaunchSpec(opts, args)


def get_env(opts: LaunchCLIOptions, active_child: Child | None = None, base_env: dict[str, str] | None = None) -> dict[str, str]:
    env: dict[str, str] = {}
    if opts.copy_env and active_child:
        env.update(active_child.foreground_environ)
    if base_env is not None:
        env.update(base_env)
    for x in opts.env:
        for k, v in parse_env(x, env):
            env[k] = v
    return env


def layer_shell_config_from_panel_opts(panel_opts: Iterable[str]) -> LayerShellConfig:
    from kittens.panel.main import layer_shell_config, parse_panel_args

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Print/inspect the exact args list passed and compare with kitty launch --help.
2. Quote CLI strings properly when building them in shell/Python.
3. After upgrading kitty, re-check option names in the error message.

Example fix

# before
parse_launch_args(['--typ', 'overlay'])
# after
parse_launch_args(['--type', 'overlay'])

from kitty.launch import parse_launch_args
# pre-flight: kitty launch --help equivalent via parse and catch

try:
    spec = parse_launch_args(args)
except ValueError as e:
    show_user_friendly_error(str(e)); return

When it happens

Trigger: Any malformed --launch options string passed to launch, add_window, clone-decode, or response_from_kitty: unknown flags, bad value types, missing required values.

Common situations: kitty @ launch / remote-control commands with typos in flags; kittens composing launch options programmatically; option removed/renamed across kitty versions.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Unknown type_of_input: {type_of_input}
• usage: kitty +launch script.py [arguments to be passed to sc
• {panel args parse error}
• --hold-after-ssh can only be supplied if --cwd=current or si
• The cmd to run must be specified when running a background p

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