kovidgoyal/kitty · error · RemoteControlErrorWithoutTraceback

Must specify at least one panel setting

Error message

Must specify at least one panel setting

What it means

Raised when the os-panel action is dispatched with no panel settings in the payload. kitty requires at least one panel option (e.g. edge, size, margins) to build or update a layer-shell configuration; an empty 'os_panel' payload leaves nothing to apply.

Source

Thrown at kitty/rc/resize_os_window.py:130

            toggle_os_window_visibility,
        )

        windows = self.windows_for_match_payload(boss, window, payload_get)
        if windows:
            ac = payload_get('action')
            for os_window_id in {w.os_window_id for w in windows if w}:
                metrics = get_os_window_size(os_window_id)
                if metrics is None:
                    raise RemoteControlErrorWithoutTraceback(f'The OS Window {os_window_id} does not exist')
                panels = payload_get('os_panel')
                is_panel = metrics['is_layer_shell']
                if ac == 'os-panel':
                    if not is_panel:
                        raise RemoteControlErrorWithoutTraceback(
                            f'The OS Window {os_window_id} is not a panel you should not use the --action=resize option to resize it'
                        )
                    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):

View on GitHub (pinned to 6d5d0c4406)

Solutions

  1. Add at least one panel option, e.g. --os-panel-edge, --os-panel-size, --os-panel-margin, or --os-panel-exclusive
  2. If scripting, assert the options dict is non-empty before sending the command
  3. Check option spelling against kitten @ resize-os-window --help for the panel sub-options

Example fix

# before
kitten @ resize-os-window --action=os-panel
# after
kitten @ resize-os-window --action=os-panel --os-panel-size=48
Defensive patterns

Strategy: validation

Validate before calling

panels = {'edge': 'top', 'size': 40}
assert panels, 'at least one os_panel option required'
send({'cmd': 'resize_os_window', 'action': 'os-panel', 'os_panel': panels})

Prevention

When it happens

Trigger: kitten @ resize-os-window --action=os-panel with no --os-panel-* options supplied, or an RPC payload where the os_panel dict is empty/None.

Common situations: Automation that builds panel options conditionally and ends up passing none; typo'd option names so the CLI parser never populates os_panel; invoking the raw remote-control command dict without the os_panel key.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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