kovidgoyal/kitty · error · RemoteControlErrorWithoutTraceback

The OS Window {os_window_id} is not a panel you should not u

Error message

The OS Window {os_window_id} is not a panel you should not use the --action=resize option to resize it

What it means

Raised by kitty's remote control 'resize-os-window --action=os-panel' handler when the targeted OS window is not a layer-shell panel. kitty only permits the os-panel action on windows created as desktop panels (layer-shell surfaces, via kittens.panel), because panel resizing works by updating the layer-shell configuration rather than normal window resizing. The check uses metrics['is_layer_shell'] from the window's backend metrics.

Source

Thrown at kitty/rc/resize_os_window.py:126

            get_os_window_size,
            layer_shell_config_for_os_window,
            set_layer_shell_config,
            toggle_fullscreen,
            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:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Verify the target is a panel first: query the window (kitty @ ls / get-window-metrics equivalent) and confirm is_layer_shell is true
2. Fix the --match expression so it selects the panel window, not the parent kitty window
3. Create the panel with the panel launch type (kitten @ launch --type=panel ...) before running os-panel actions
4. If you want to resize a normal window, use --action=resize instead of --action=os-panel

Example fix

# before
kitten @ resize-os-window --match id:1 --action=os-panel --os-panel-edge=top
# after (create/launch a panel, then target it)
kitten @ launch --type=panel --panel-edge=top --match id:1 some-cmd
kitten @ resize-os_window --match id:2 --action=os-panel --os-panel-size=40

import subprocess, json
ls = json.loads(subprocess.check_output(['kitten','@','ls']))
w = next(w for w in ls for t in w['tabs'] for w in t['windows'])
# confirm panel status before os-panel action
assert w.get('is_layer_shell') or 'panel' in (w.get('title') or '').lower(), 'not a panel window'

try:
    kitten @ resize-os-window --action=os-panel ...
except RCError as e:
    if 'is not a panel' in str(e): target_regular_window_instead()

When it happens

Trigger: Calling resize-os-window with action=os-panel targeting a normal (non-panel) OS window id, e.g. kitten @ resize-os-window --match id:1 --action=os-panel --os-panel-edge=top on a regular terminal window.

Common situations: Scripts that assume any window id can be turned into a panel; using the wrong --match expression so the action lands on the main kitty window instead of the panel window; copying panel commands from docs without first creating the panel via kitten @ launch --type=panel.

Related errors

• The OS Window {os_window_id} is a desktop panel, no actions
• The OS Window {os_window_id} has no panel configuration
• Failed to change panel configuration for OS Window {os_windo
• The OS Window {os_window_id} is a desktop panel that cannot
• The OS Window {os_window_id} is a panel and cannot be resize

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