kovidgoyal/kitty · error · RemoteControlErrorWithoutTraceback

Invalid panel options specified: {e}

Error message

Invalid panel options specified: {e}

What it means

Raised when the panel options payload fails validation in kitty.launch.layer_shell_config_from_panel_opts. The parser expects a dict of recognized panel keys (edge, size, margin, exclusive zone, layer, keyboard interactivity, etc.); unknown keys or bad value types raise, and the handler re-raises as Invalid panel options specified: {e} with the underlying message.

Source

Thrown at kitty/rc/resize_os_window.py:147

                    if not panels:
                        raise RemoteControlErrorWithoutTraceback('Must specify at least one panel setting')
                    if payload_get('incremental'):
                        existing = layer_shell_config_for_os_window(os_window_id)
                        if existing is None:
                            raise RemoteControlErrorWithoutTraceback(f'The OS Window {os_window_id} has no panel configuration')
                        from kittens.panel.main import incrementally_update_layer_shell_config

                        try:
                            lsc = incrementally_update_layer_shell_config(existing, panels)
                        except Exception as e:
                            raise RemoteControlErrorWithoutTraceback(str(e))
                    else:
                        from kitty.launch import layer_shell_config_from_panel_opts

                        try:
                            lsc = layer_shell_config_from_panel_opts(panels)
                        except Exception as e:
                            raise RemoteControlErrorWithoutTraceback(f'Invalid panel options specified: {e}')
                    if not set_layer_shell_config(os_window_id, lsc):
                        raise RemoteControlErrorWithoutTraceback(f'Failed to change panel configuration for OS Window {os_window_id}')
                elif ac == 'toggle-visibility':
                    toggle_os_window_visibility(os_window_id)
                elif ac == 'hide':
                    toggle_os_window_visibility(os_window_id, False)
                elif ac == 'show':
                    toggle_os_window_visibility(os_window_id, True)
                elif ac == 'toggle-fullscreen':
                    if not toggle_fullscreen(os_window_id):
                        raise RemoteControlErrorWithoutTraceback(f'The OS Window {os_window_id} is a desktop panel that cannot be made fullscreen')
                elif is_panel:
                    raise RemoteControlErrorWithoutTraceback(
                        f'The OS Window {os_window_id} is a desktop panel, no actions other than resizing are supported for it'
                    )
                elif ac == 'resize':
                    boss.resize_os_window(
                        os_window_id,

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Read the underlying message after the colon — it names the failing key/value
2. Validate keys/types against kitty.launch layer_shell config options (edge in top/bottom/left/right, numeric size/margins, boolean exclusive)
3. Prefer the documented CLI flags (kitten @ resize-os-window --os-panel-*) so the CLI parser normalizes values for you
4. Update both client and server kitty versions to match

Example fix

# before (raw payload)
{'cmd': 'resize_os_window', 'action': 'os-panel', 'os_panel': {'edge': 'Top', 'size': '40'}}
# after
{'cmd': 'resize_os_window', 'action': 'os-panel', 'os_panel': {'edge': 'top', 'size': 40}}

ALLOWED = {'edge', 'size', 'margin', 'exclusive', 'layer', 'keyboard_interactivity'}
panels = {k: v for k, v in panels.items() if k in ALLOWED}
assert panels.get('edge') in {'top','bottom','left','right'}
assert isinstance(panels.get('size'), int)

try:
    apply_panel_opts(win, panels)
except RCError as e:
    if str(e).startswith('Invalid panel options'):
        log_bad_payload(panels); fix_and_retry(panels)

When it happens

Trigger: Passing unrecognized keys or wrong types in the os_panel payload, e.g. {'edge': 'diagonal'} or a string size where a number is required.

Common situations: Sending raw RPC payloads built by hand instead of via the CLI; version skew where option names changed between kitty releases; JSON numbers sent as strings.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unknown type_of_input: {type_of_input}
• The OS Window {os_window_id} is not a panel you should not u
• Must specify at least one panel setting
• The OS Window {os_window_id} has no panel configuration
• Failed to change panel configuration for OS Window {os_windo

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