{"record":{"id":"739ff3d8f48823ba","repo":"kovidgoyal/kitty","slug":"the-matched-window-is-not-currently-visible-scree","errorCode":null,"errorMessage":"The matched window is not currently visible, screenshots can only be taken of visible windows","messagePattern":"The matched window is not currently visible, screenshots can only be taken of visible windows","errorType":"exception","errorClass":"RemoteControlErrorWithoutTraceback","httpStatus":null,"severity":"error","filePath":"kitty/rc/screenshot.py","lineNumber":80,"sourceCode":"            'match_tab': opts.match_tab,\n            'output_path': args[0] if args else '',\n        }\n\n    def response_from_kitty(self, boss: Boss, window: Window | None, payload_get: PayloadGetType) -> ResponseType:\n        match = payload_get('match')\n        match_tab = payload_get('match_tab')\n        target_window_id = 0\n        include_tab_bar = False\n\n        if match:\n            windows = list(boss.match_windows(match, window))\n            if not windows:\n                raise MatchError(match)\n            w = windows[0]\n            tab = w.tabref()\n            tm = tab.tab_manager_ref() if tab is not None else None\n            if tab is None or tm is None or tm.active_tab is not tab or not w.is_visible_in_layout:\n                raise RemoteControlErrorWithoutTraceback('The matched window is not currently visible, screenshots can only be taken of visible windows')\n            os_window_id = w.os_window_id\n            target_window_id = w.id\n        elif match_tab:\n            tabs = list(boss.match_tabs(match_tab))\n            if not tabs:\n                raise MatchError(match_tab, 'tabs')\n            tab = tabs[0]\n            tm = tab.tab_manager_ref()\n            if tm is None or tm.active_tab is not tab:\n                raise RemoteControlErrorWithoutTraceback('The matched tab is not currently visible, screenshots can only be taken of visible tabs')\n            os_window_id = tab.os_window_id\n        else:\n            atm = boss.active_tab_manager\n            if atm is None:\n                raise RemoteControlErrorWithoutTraceback('There is no active OS window to screenshot')\n            os_window_id = atm.os_window_id\n            include_tab_bar = True\n","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/rc/screenshot.py#L62-L98","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Switch to the tab/focus the window first (kitten @ focus-tab --match, kitten @ focus-window --match) and let the layout make it visible","Take the screenshot of the whole OS window instead: omit window match or use the tab/OS-window forms","Re-check the target is on an active tab before capturing (kitty @ ls shows tab activity/active_window)"],"exampleFix":"# before\nkitten @ screenshot --match id:12 --match-tab id:3\n# after\nkitten @ focus-tab --match id:3 && kitten @ screenshot --match id:12","handlingStrategy":"validation","validationCode":"import json, subprocess\nls = json.loads(subprocess.check_output(['kitten','@','ls']))\nw = find_window(ls, match)\nwin = w['window']; tab = w['tab']; os_win = w['os_window']\nif not (win['is_visible_in_layout'] and tab.get('is_active') and os_win.get('is_active')):\n    subprocess.run(['kitten','@','focus-window','--match', f'id:{win[\"id\"]}'])","typeGuard":"def is_capturable(w: dict, tab: dict) -> bool:\n    return bool(w.get('is_visible_in_layout')) and tab.get('is_focused', False)","tryCatchPattern":"try:\n    capture(match)\nexcept RCError as e:\n    if 'not currently visible' in str(e):\n        focus_window(match); capture(match)","preventionTips":["Focus the target window/tab immediately before capturing","Prefer OS-window-level screenshots for automation","Re-query kitty @ ls right before capture to avoid stale ids"],"tags":["kitty","remote-control","screenshot","window-matching","visibility"],"backgroundTag":"invalid-window-target","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}