kovidgoyal/kitty · error · ValueError

{panel args parse error}

Error message

{panel args parse error}

What it means

layer_shell_config_from_panel_opts normalizes panel options (auto-prefixing '--') and runs the panel kitten's parser; its SystemExit is converted to ValueError so callers like create_tab/response_from_kitty can handle bad panel options programmatically.

Source

Thrown at kitty/launch.py:464

    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

    args = [('' if x.startswith('--') else '--') + x for x in panel_opts]
    try:
        opts, _ = parse_panel_args(args)
    except SystemExit as e:
        raise ValueError(str(e))
    return layer_shell_config(opts)


def parse_os_window_position(position: str | None) -> tuple[int | None, int | None]:
    if not position:
        return None, None
    x, _, y = position.lower().partition('x')
    return int(x), int(y)


def tab_for_window(boss: Boss, opts: LaunchCLIOptions, target_tab: Tab | None, next_to: Window | None, add_to_session: str) -> Tab:

    def create_tab(tm: TabManager | None = None) -> Tab:
        if tm is None:
            if opts.type == 'os-panel':
                oswid = boss.add_os_panel(layer_shell_config_from_panel_opts(opts.os_panel), opts.os_window_class, opts.os_window_name)
            else:
                x, y = (None, None) if is_wayland() else parse_os_window_position(opts.os_window_position)

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Run the panel kitten with --help and use exact flag names.
2. Let the helper auto-prefix '--' rather than mixing formats yourself.
3. Upgrade/downgrade to the kitty version whose panel kitten matches your flags.

Example fix

# before
layer_shell_config_from_panel_opts(['layerr', 'top'])
# after
layer_shell_config_from_panel_opts(['layer', 'top'])

# pre-validate panel opts against the panel kitten parser
opts, _ = parse_panel_args([('--' if not a.startswith('--') else '') + a for a in panel_opts])

try:
    cfg = layer_shell_config_from_panel_opts(panel_opts)
except ValueError as e:
    logging.error('bad panel opts: %s', e); return None

When it happens

Trigger: Passing panel_opts containing unknown or malformed panel-kitten flags when creating a layer-shell panel window (e.g. on Wayland panel integration).

Common situations: Typos in panel options; flags supported only by newer panel kittens; building opts dynamically and passing bare values without '--'.

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

• Creating desktop panels is not supported on this platform
• The OS Window {os_window_id} is a panel and cannot be resize
• {argparse error from SystemExit}
• Failed to change panel configuration for OS Window {os_windo
• Failed to start tab drag: {e}

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