kovidgoyal/kitty · error · RemoteControlErrorWithoutTraceback

Failed to change panel configuration for OS Window {os_windo

Error message

Failed to change panel configuration for OS Window {os_window_id}

What it means

Raised when set_layer_shell_config returns falsy, meaning kitty's backend failed to apply the new layer-shell configuration to the window. This is a compositor/protocol-level failure: the wlr-layer-shell protocol negotiation or apply request did not succeed, not a payload problem.

Source

Thrown at kitty/rc/resize_os_window.py:149

                    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,
                        width=payload_get('width'),
                        height=payload_get('height'),

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Confirm you are on Wayland with a compositor supporting wlr-layer-shell (sway, Hyprland, most wlroots compositors)
2. Retry after re-checking the window still exists (kitty @ ls) — the surface may have died mid-command
3. Recreate the panel and reapply the configuration
4. If the compositor genuinely lacks layer-shell, use a normal window + --action=resize instead of panels

import os
assert os.environ.get('WAYLAND_DISPLAY'), 'layer-shell panels need Wayland'
# optional: check compositor advertises wlr-layer-shell via wayland-info

try:
    apply_panel_config(win, lsc)
except RCError as e:
    if 'Failed to change panel configuration' in str(e):
        fall_back_to_normal_window_resize(win)

When it happens

Trigger: Running os-panel resize on Wayland setups where the compositor does not support wlr-layer-shell or rejects the requested configuration; the window's layer surface having been destroyed concurrently.

Common situations: Running kitty on wlroots-incompatible compositors (some GNOME/Mir setups); panel surface already closed when the command arrives; racing a panel close with a resize script.

Related errors

• The OS Window {os_window_id} is not a panel you should not u
• The OS Window {os_window_id} has no panel configuration
• The OS Window {os_window_id} is a desktop panel that cannot
• The OS Window {os_window_id} is a desktop panel, no actions
• Wayland: Did not get activation token from compositor. Use a

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