kovidgoyal/kitty · error · RemoteControlErrorWithoutTraceback

The matched window is not currently visible, screenshots can

Error message

The matched window is not currently visible, screenshots can only be taken of visible windows

What it means

Raised by the screenshot command when a window match succeeds but the matched window is not visible: its tab is not the active tab of its OS window, the tab manager is gone, or the window is hidden in the layout (is_visible_in_layout false). kitty can only grab pixels for windows currently rendered on screen.

Source

Thrown at kitty/rc/screenshot.py:80

            'match_tab': opts.match_tab,
            'output_path': args[0] if args else '',
        }

    def response_from_kitty(self, boss: Boss, window: Window | None, payload_get: PayloadGetType) -> ResponseType:
        match = payload_get('match')
        match_tab = payload_get('match_tab')
        target_window_id = 0
        include_tab_bar = False

        if match:
            windows = list(boss.match_windows(match, window))
            if not windows:
                raise MatchError(match)
            w = windows[0]
            tab = w.tabref()
            tm = tab.tab_manager_ref() if tab is not None else None
            if tab is None or tm is None or tm.active_tab is not tab or not w.is_visible_in_layout:
                raise RemoteControlErrorWithoutTraceback('The matched window is not currently visible, screenshots can only be taken of visible windows')
            os_window_id = w.os_window_id
            target_window_id = w.id
        elif match_tab:
            tabs = list(boss.match_tabs(match_tab))
            if not tabs:
                raise MatchError(match_tab, 'tabs')
            tab = tabs[0]
            tm = tab.tab_manager_ref()
            if tm is None or tm.active_tab is not tab:
                raise RemoteControlErrorWithoutTraceback('The matched tab is not currently visible, screenshots can only be taken of visible tabs')
            os_window_id = tab.os_window_id
        else:
            atm = boss.active_tab_manager
            if atm is None:
                raise RemoteControlErrorWithoutTraceback('There is no active OS window to screenshot')
            os_window_id = atm.os_window_id
            include_tab_bar = True

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Switch to the tab/focus the window first (kitten @ focus-tab --match, kitten @ focus-window --match) and let the layout make it visible
2. Take the screenshot of the whole OS window instead: omit window match or use the tab/OS-window forms
3. Re-check the target is on an active tab before capturing (kitty @ ls shows tab activity/active_window)

Example fix

# before
kitten @ screenshot --match id:12 --match-tab id:3
# after
kitten @ focus-tab --match id:3 && kitten @ screenshot --match id:12

import json, subprocess
ls = json.loads(subprocess.check_output(['kitten','@','ls']))
w = find_window(ls, match)
win = w['window']; tab = w['tab']; os_win = w['os_window']
if not (win['is_visible_in_layout'] and tab.get('is_active') and os_win.get('is_active')):
    subprocess.run(['kitten','@','focus-window','--match', f'id:{win["id"]}'])

def is_capturable(w: dict, tab: dict) -> bool:
    return bool(w.get('is_visible_in_layout')) and tab.get('is_focused', False)

try:
    capture(match)
except RCError as e:
    if 'not currently visible' in str(e):
        focus_window(match); capture(match)

When it happens

Trigger: kitten @ screenshot --match id:<window-id> where that window is in a background tab, a hidden split, or its tab was closed (tabref/tab_manager_ref None).

Common situations: Screenshotting a window by stable id after the user switched tabs; scripts that iterate all windows from kitty @ ls without checking visibility; targeting a background tab's window during automation.

Related errors

• The matched tab is not currently visible, screenshots can on
• The OS Window {os_window_id} is not a panel you should not u
• The OS Window {os_window_id} is a desktop panel, no actions
• There is no active OS window to screenshot
• Must specify at most one output file

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