stablyai/orca · warning · RuntimeError

windowId is not supported by the Linux AT-SPI provider; use

Error message

windowId is not supported by the Linux AT-SPI provider; use windowIndex

What it means

Raised by choose_window (runtime.py:148-149) when window_id is not None — i.e., the operation JSON included a 'windowId' field. The Linux AT-SPI provider does not support stable window ids (AT-SPI windows have no durable identifier, only positional indices), so any non-null windowId is rejected unconditionally with a message redirecting to windowIndex. This is a hard API contract: windowId is the macOS concept; windowIndex is the Linux equivalent.

Source

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

            yield app


def windows_for(app):
    result = []
    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):

View on GitHub (pinned to 1136503c6a)

Solutions

1. Replace 'windowId' with 'windowIndex' in the operation JSON for Linux targets — use the index returned in make_snapshot's windowIndex field.
2. On the caller side, branch by platform: send windowId on macOS, windowIndex on Linux.
3. Strip windowId before dispatching to the Linux runtime so choose_window never sees it.
4. If you need stable targeting across window reorders, target by element index within a fresh get-app-state snapshot instead.

Example fix

// before — cross-platform op uses windowId
{ "app": "Firefox", "windowId": "main", "tool": "click", "x": 10, "y": 10 }

// after — Linux uses windowIndex
{ "app": "Firefox", "windowIndex": 0, "tool": "click", "x": 10, "y": 10 }

# Strip windowId for Linux before dispatch
op = dict(operation)
if op.get('windowId') is not None:
    op.pop('windowId')
    # or translate to windowIndex if you have one
    if 'windowIndex' not in op:
        op['windowIndex'] = 0  # let choose_window pick active/showing/first

def is_linux_window_id_unsupported(operation: dict) -> bool:
    return operation.get('windowId') is not None

try:
    run_operation(operation)
except RuntimeError as exc:
    if 'windowId is not supported' in str(exc):
        operation = {k: v for k, v in operation.items() if k != 'windowId'}
        operation['windowIndex'] = 0
        run_operation(operation)
    else:
        raise

When it happens

Trigger: run_operation received an operation dict where operation.get('windowId') returned a non-null value. Caused by a cross-platform caller that always populates windowId, or by an agent that read a snapshot's 'windowId' field (always null on Linux, see line 670) and echoed it back as a target.

Common situations: An agent or orchestrator built against the macOS computer-use API invoking the Linux bridge unchanged; a snapshot consumer that didn't notice windowId is null on Linux and tried to target a window by id.

Related errors

• No top-level AT-SPI window is available for {app}
• windowNotFound("{window_index}")
• window_not_focused: keyboard input requires the target windo
• window_not_focused: keyboard input requires the target windo
• Linux computer use requires an active desktop session; missi

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