{"record":{"id":"79e3bea72669f912","repo":"stablyai/orca","slug":"windownotfound-window-index","errorCode":null,"errorMessage":"windowNotFound(\"{window_index}\")","messagePattern":"windowNotFound\\(\"(.+?)\"\\)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"native/computer-use-linux/runtime.py","lineNumber":154,"sourceCode":"    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\n    component = attempt(target.get_component_iface)\n    if component is not None and attempt(lambda: Atspi.Component.grab_focus(component), False):\n        return\n    pid = pid_of(app)\n    if not pid or not shutil.which(\"xdotool\"):\n        return\n    subprocess.run(","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/native/computer-use-linux/runtime.py#L136-L172","documentation":"Raised by choose_window (runtime.py:150-154) when window_index was provided (not None) but no window in windows_for(app) has a matching index. The window list is built fresh each call via windows_for, indexed by the child's position in the AT-SPI app children list; if windows were closed, opened, or reordered since the caller obtained the index, the requested index may no longer exist. The error echoes the requested index in a windowNotFound(\"...\") envelope.","triggerScenarios":"operation.get('windowIndex') returned a value N, but iterating windows_for(app) (rebuilt from the live AT-SPI tree) yielded no item whose [0] === int(N). Caused by stale index from a prior snapshot: between get-app-state and the action call, the app opened/closed windows, changing child positions, or the app's AT-SPI children list shifted.","commonSituations":"Agent cached a windowIndex from an old snapshot and reused it after UI churn (dialogs opened/closed, tabs dragged to new windows, multiple windows reordered by focus). Also hits when the app dynamically adds/removes children (animations, splash screens) between calls.","solutions":["Call get-app-state (make_snapshot) immediately before the action and use the fresh windowIndex from its response.","If the window identity matters more than position, target the active window by omitting windowIndex entirely — choose_window falls back to ACTIVE then SHOWING then windows[0].","After window-changing actions (open/close), refresh the snapshot before the next indexed operation.","Wrap actions in a retry that re-snapshots on windowNotFound and re-targets."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"# Before choose_window, validate the requested index exists\nwindows = windows_for(app)\nvalid_indices = {item[0] for item in windows}\nif window_index is not None and int(window_index) not in valid_indices:\n    # refresh snapshot, or fall back to active window\n    window_index = None  # let choose_window pick ACTIVE/SHOWING/first","typeGuard":"def is_valid_window_index(app, window_index) -> bool:\n    return any(item[0] == int(window_index) for item in windows_for(app))","tryCatchPattern":"try:\n    window = choose_window(app, window_index=idx)\nexcept RuntimeError as exc:\n    if str(exc).startswith('windowNotFound('):\n        # refresh snapshot and retry with active-window fallback\n        snapshot = make_snapshot(query, include_screenshot=False)\n        window = choose_window(app)  # let it pick active/showing/first\n    else:\n        raise","preventionTips":["Call get-app-state immediately before indexed window operations and use the fresh windowIndex.","After window-changing actions, refresh the snapshot before re-targeting.","Prefer omitting windowIndex (let choose_window pick active) when identity matters less than presence."],"tags":["linux","at-spi","window","staleness","index"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}