kovidgoyal/kitty · error · RuntimeError

Creating desktop panels is not supported on this platform

Error message

Creating desktop panels is not supported on this platform

What it means

Boss.add_os_panel raises RuntimeError when creating a layer-shell desktop panel (dock/panel window) is requested but the platform lacks Wayland layer-shell support. Panels are only implementable via the wlr-layer-shell protocol on Wayland.

Source

Thrown at kitty/boss.py:525

                    pre_show_callback,
                    wtitle or appname,
                    wname,
                    wclass,
                    wstate,
                    disallow_override_title=bool(wtitle),
                    x=x,
                    y=y,
                )
        else:
            wname = self.args.name or self.args.cls or appname
            wclass = self.args.cls or appname
        tm = TabManager(os_window_id, self.args, wclass, wname, startup_session)
        self.os_window_map[os_window_id] = tm
        return os_window_id

    def add_os_panel(self, cfg: LayerShellConfig, wclass: str | None = appname, wname: str | None = appname) -> int:
        if not is_layer_shell_supported():
            raise RuntimeError('Creating desktop panels is not supported on this platform')
        wclass = wclass or appname
        wname = wname or appname
        size_data = get_os_window_sizing_data(get_options(), None)
        os_window_id = create_os_window(initial_window_size_func(size_data, {}), lambda *a: None, appname, wname, wclass, None, layer_shell_config=cfg)
        tm = TabManager(os_window_id, self.args, wclass, wname, None)
        self.os_window_map[os_window_id] = tm
        return os_window_id

    def list_os_windows(
        self, self_window: Window | None = None, tab_filter: Callable[[Tab], bool] | None = None, window_filter: Callable[[Window], bool] | None = None
    ) -> Iterator[OSWindowDict]:
        with cached_process_data():
            active_tab_manager = self.active_tab_manager
            focused_wid = current_focused_os_window_id()
            last_focused = last_focused_os_window_id()
            for os_window_id, tm in self.os_window_map.items():
                tabs = list(tm.list_tabs(self_window, tab_filter, window_filter))
                if tabs:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Switch to a Wayland session with a layer-shell compositor (sway, most wlroots compositors)
2. Remove/disable the panel configuration on unsupported platforms
3. Guard calls with is_layer_shell_supported() before add_os_panel

Example fix

# before
boss.add_os_panel(cfg)
# after
from kitty.boss import is_layer_shell_supported
if is_layer_shell_supported():
    boss.add_os_panel(cfg)

from kitty.boss import is_layer_shell_supported
if is_layer_shell_supported():
    boss.add_os_panel(cfg)

def can_add_panel() -> bool:
    from kitty.boss import is_layer_shell_supported
    return is_layer_shell_supported()

try:
    boss.add_os_panel(cfg)
except RuntimeError as e:
    if 'not supported on this platform' in str(e):
        skip_panels = True
    else:
        raise

When it happens

Trigger: Calling add_os_panel(cfg, ...) on X11, macOS, or a compositor without layer-shell support (is_layer_shell_supported() returns False); triggered via remote control/single-instance commands that create panels.

Common situations: Running a config, session, or script that defines OS panels while kitty runs on X11 or macOS; or on a Wayland compositor that does not implement layer-shell.

Related errors

• The OS Window {os_window_id} is a panel and cannot be resize
• {panel args parse error}
• Failed to change panel configuration for OS Window {os_windo
• The OS Window {os_window_id} is not a panel you should not u
• The OS Window {os_window_id} has no panel configuration

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