stablyai/orca · error · RuntimeError

windowNotFound("{window_index}")

Error message

windowNotFound("{window_index}")

What it means

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.

Source

Thrown at native/computer-use-linux/runtime.py:154

    for index, child in children(app):
        role = role_of(child).lower()
        rect = screen_rect(child)
        if rect is not None or role in {"frame", "window", "dialog", "alert"}:
            result.append((index, child))
    return result


def choose_window(app, window_id=None, window_index=None):
    windows = windows_for(app)
    if not windows:
        raise RuntimeError("No top-level AT-SPI window is available for " + name_of(app))
    if window_id is not None:
        raise RuntimeError("windowId is not supported by the Linux AT-SPI provider; use windowIndex")
    if window_index is not None:
        for item in windows:
            if item[0] == int(window_index):
                return item
        raise RuntimeError(f'windowNotFound("{window_index}")')
    for item in windows:
        if has_state(item[1], Atspi.StateType.ACTIVE):
            return item
    for item in windows:
        if has_state(item[1], Atspi.StateType.SHOWING):
            return item
    return windows[0]


def restore_window(app, window=None):
    target = window if window is not None else app
    component = attempt(target.get_component_iface)
    if component is not None and attempt(lambda: Atspi.Component.grab_focus(component), False):
        return
    pid = pid_of(app)
    if not pid or not shutil.which("xdotool"):
        return
    subprocess.run(

View on GitHub (pinned to 1136503c6a)

Solutions

1. Call get-app-state (make_snapshot) immediately before the action and use the fresh windowIndex from its response.
2. 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].
3. After window-changing actions (open/close), refresh the snapshot before the next indexed operation.
4. Wrap actions in a retry that re-snapshots on windowNotFound and re-targets.

# Before choose_window, validate the requested index exists
windows = windows_for(app)
valid_indices = {item[0] for item in windows}
if window_index is not None and int(window_index) not in valid_indices:
    # refresh snapshot, or fall back to active window
    window_index = None  # let choose_window pick ACTIVE/SHOWING/first

def is_valid_window_index(app, window_index) -> bool:
    return any(item[0] == int(window_index) for item in windows_for(app))

try:
    window = choose_window(app, window_index=idx)
except RuntimeError as exc:
    if str(exc).startswith('windowNotFound('):
        # refresh snapshot and retry with active-window fallback
        snapshot = make_snapshot(query, include_screenshot=False)
        window = choose_window(app)  # let it pick active/showing/first
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• No top-level AT-SPI window is available for {app}
• windowId is not supported by the Linux AT-SPI provider; use
• window_not_focused: keyboard input requires the target windo
• window_not_focused: keyboard input requires the target windo
• stale element frame; run get-app-state again and use a fresh

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/79e3bea72669f912. Report an issue: GitHub.