stablyai/orca · error · RuntimeError

appNotFound("{query}")

Error message

appNotFound("{query}")

What it means

Raised by find_app (runtime.py:212-217) when no desktop application matched the query string. app_matches checks: prefix 'pid:' for exact PID match, a bare positive integer matching pid_of(app), or substring/equality on the lowercased app name or any of its window names. If none of desktop_apps() (apps with a non-empty name on the AT-SPI desktop root) satisfy the query, find_app raises appNotFound("<query>") echoing the original query.

Source

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

    if needle.startswith("pid:"):
        requested_pid = parse_positive_pid(needle[4:])
        return requested_pid is not None and pid_of(app) == requested_pid
    if needle.isdigit() and int(needle) > 0 and pid_of(app) == int(needle):
        return True
    haystacks = [name_of(app).lower()] + [name_of(window).lower() for _, window in windows_for(app)]
    return any(value == needle or needle in value for value in haystacks)


def parse_positive_pid(value):
    return int(value) if value.isdigit() and int(value) > 0 else None


def find_app(query):
    for app in desktop_apps():
        if app_matches(app, query):
            reject_blocked_app(app)
            return app
    raise RuntimeError(f'appNotFound("{query}")')


def reject_blocked_app(app):
    haystacks = [name_of(app).lower()] + [name_of(window).lower() for _, window in windows_for(app)]
    if any(fragment in value for fragment in BLOCKED_APP_FRAGMENTS for value in haystacks):
        raise RuntimeError(f'appBlocked("{name_of(app)}")')


def action_labels(node):
    labels = []
    count = int(attempt(node.get_n_actions, 0) or 0)
    for index in range(count):
        label = str(attempt(lambda i=index: node.get_action_name(i), "") or "")
        description = str(attempt(lambda i=index: node.get_action_description(i), "") or "")
        value = label or description
        if value and value not in labels:
            labels.append(value)
    return labels

View on GitHub (pinned to 1136503c6a)

Solutions

1. Call list_apps first and use the exact 'name' (or 'pid') from the response as the query.
2. If unsure of exact name, use a distinctive substring that appears in the app or window title.
3. Use 'pid:<pid>' for unambiguous targeting when you know the process id.
4. If the app was just launched, retry after a moment for the AT-SPI registry to register it.

# Before find_app, verify the query matches a known app
apps = list_apps_response()
names = {a['name'].lower() for a in apps}
needle = str(query or '').strip().lower()
if not any(needle in n or n in needle for n in names) and not needle.startswith('pid:'):
    raise SystemExit(f'appNotFound preempted: {query!r}. Known: {sorted(names)}')

def app_query_is_known(query) -> bool:
    if not query: return False
    if str(query).startswith('pid:'): return True
    needle = str(query).strip().lower()
    return any(needle in name_of(app).lower() for app in desktop_apps())

try:
    app = find_app(query)
except RuntimeError as exc:
    if str(exc).startswith('appNotFound('):
        # list apps and either retry with a corrected name or surface to caller
        apps = list_apps_response()
        raise SystemExit(f'{exc}. Known apps: {[a["name"] for a in apps]}')
    raise

When it happens

Trigger: operation.get('app','') returned a query that no AT-SPI app matches: typo in app name, app not running, app registered under a different name (e.g., binary name vs window title), or query format mismatch (e.g., 'pid:' with non-numeric, or expecting a bundle id that doesn't exist on Linux).

Common situations: Agent used a macOS bundleIdentifier-style name that doesn't match the Linux AT-SPI app name; app launched but AT-SPI registry hasn't exposed it yet; sandboxed app (flatpak) reports a prefixed/munged name; case-sensitivity surprise (matching is lowercased but the substring must still appear).

Related errors

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

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