{"record":{"id":"bc04f7ff24d45da3","repo":"stablyai/orca","slug":"no-top-level-at-spi-window-is-available-for-app","errorCode":null,"errorMessage":"No top-level AT-SPI window is available for {app}","messagePattern":"No top-level AT-SPI window is available for (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"native/computer-use-linux/runtime.py","lineNumber":147,"sourceCode":"    for _, app in children(desktop_root()):\n        if name_of(app):\n            yield app\n\n\ndef windows_for(app):\n    result = []\n    for index, child in children(app):\n        role = role_of(child).lower()\n        rect = screen_rect(child)\n        if rect is not None or role in {\"frame\", \"window\", \"dialog\", \"alert\"}:\n            result.append((index, child))\n    return result\n\n\ndef choose_window(app, window_id=None, window_index=None):\n    windows = windows_for(app)\n    if not windows:\n        raise RuntimeError(\"No top-level AT-SPI window is available for \" + name_of(app))\n    if window_id is not None:\n        raise RuntimeError(\"windowId is not supported by the Linux AT-SPI provider; use windowIndex\")\n    if window_index is not None:\n        for item in windows:\n            if item[0] == int(window_index):\n                return item\n        raise RuntimeError(f'windowNotFound(\"{window_index}\")')\n    for item in windows:\n        if has_state(item[1], Atspi.StateType.ACTIVE):\n            return item\n    for item in windows:\n        if has_state(item[1], Atspi.StateType.SHOWING):\n            return item\n    return windows[0]\n\n\ndef restore_window(app, window=None):\n    target = window if window is not None else app","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/native/computer-use-linux/runtime.py#L129-L165","documentation":"Raised by choose_window (runtime.py:144-147) when windows_for(app) returns an empty list — the matched application exposes no top-level AT-SPI children classified as windows. windows_for keeps a child only if it has a screen rect OR its role is in {frame, window, dialog, alert}; an app with zero such children triggers this. The error names the app via name_of(app) so the caller knows which application lacks a usable window.","triggerScenarios":"find_app matched an app (by name/pid) but the app has no visible windows: all windows closed (app is in system-tray-only/background state), windows are minimized to tray without an AT-SPI frame representation, the app exposes only menu-bar/menubar-role children, or the app is a background helper process that registered an AT-SPI app object without UI.","commonSituations":"Targeting a tray-only app (Discord, Slack, Dropbox) that was closed to tray; an app that just launched and hasn't created a window yet; a flatpak/snap app whose AT-SPI tree is sandboxed and reports no windows; a wrong app match (e.g., matched a helper process instead of the real app).","solutions":["Restore the app's window from its tray/dock before calling (some apps respond to a second launch with --activate or dbus activation).","Call list_apps first to confirm you matched the right process; use 'pid:<pid>' to disambiguate from helper processes.","Retry after a short delay if the app was just launched and the window isn't registered yet.","On flatpak/snap apps, ensure AT-SPI is accessible across the sandbox (x11 --socket, accessibility bus sharing)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"# Before choose_window, check the app has windows\nwindows = windows_for(app)\nif not windows:\n    raise SystemExit(f'App {name_of(app)} has no open windows. Restore one and retry.')","typeGuard":"def app_has_windows(app) -> bool:\n    return bool(windows_for(app))","tryCatchPattern":"try:\n    window = choose_window(app)\nexcept RuntimeError as exc:\n    if str(exc).startswith('No top-level AT-SPI window'):\n        # restore from tray / activate, then retry once\n        restore_window(app)\n        time.sleep(0.3)\n        window = choose_window(app)\n    else:\n        raise","preventionTips":["Call list_windows (list_windows_response) before targeting to confirm the app has windows.","Disambiguate helper vs real app using 'pid:<pid>' to avoid matching background processes.","Retry once after a brief delay if the app was just launched and hasn't created a window."],"tags":["linux","at-spi","window","desktop","app"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}