{"record":{"id":"728dfd476fdd3ce1","repo":"stablyai/orca","slug":"appnotfound-query","errorCode":null,"errorMessage":"appNotFound(\"{query}\")","messagePattern":"appNotFound\\(\"(.+?)\"\\)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"native/computer-use-linux/runtime.py","lineNumber":217,"sourceCode":"    if needle.startswith(\"pid:\"):\n        requested_pid = parse_positive_pid(needle[4:])\n        return requested_pid is not None and pid_of(app) == requested_pid\n    if needle.isdigit() and int(needle) > 0 and pid_of(app) == int(needle):\n        return True\n    haystacks = [name_of(app).lower()] + [name_of(window).lower() for _, window in windows_for(app)]\n    return any(value == needle or needle in value for value in haystacks)\n\n\ndef parse_positive_pid(value):\n    return int(value) if value.isdigit() and int(value) > 0 else None\n\n\ndef find_app(query):\n    for app in desktop_apps():\n        if app_matches(app, query):\n            reject_blocked_app(app)\n            return app\n    raise RuntimeError(f'appNotFound(\"{query}\")')\n\n\ndef reject_blocked_app(app):\n    haystacks = [name_of(app).lower()] + [name_of(window).lower() for _, window in windows_for(app)]\n    if any(fragment in value for fragment in BLOCKED_APP_FRAGMENTS for value in haystacks):\n        raise RuntimeError(f'appBlocked(\"{name_of(app)}\")')\n\n\ndef action_labels(node):\n    labels = []\n    count = int(attempt(node.get_n_actions, 0) or 0)\n    for index in range(count):\n        label = str(attempt(lambda i=index: node.get_action_name(i), \"\") or \"\")\n        description = str(attempt(lambda i=index: node.get_action_description(i), \"\") or \"\")\n        value = label or description\n        if value and value not in labels:\n            labels.append(value)\n    return labels","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/native/computer-use-linux/runtime.py#L199-L235","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","solutions":["Call list_apps first and use the exact 'name' (or 'pid') from the response as the query.","If unsure of exact name, use a distinctive substring that appears in the app or window title.","Use 'pid:<pid>' for unambiguous targeting when you know the process id.","If the app was just launched, retry after a moment for the AT-SPI registry to register it."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"# Before find_app, verify the query matches a known app\napps = list_apps_response()\nnames = {a['name'].lower() for a in apps}\nneedle = str(query or '').strip().lower()\nif not any(needle in n or n in needle for n in names) and not needle.startswith('pid:'):\n    raise SystemExit(f'appNotFound preempted: {query!r}. Known: {sorted(names)}')","typeGuard":"def app_query_is_known(query) -> bool:\n    if not query: return False\n    if str(query).startswith('pid:'): return True\n    needle = str(query).strip().lower()\n    return any(needle in name_of(app).lower() for app in desktop_apps())","tryCatchPattern":"try:\n    app = find_app(query)\nexcept RuntimeError as exc:\n    if str(exc).startswith('appNotFound('):\n        # list apps and either retry with a corrected name or surface to caller\n        apps = list_apps_response()\n        raise SystemExit(f'{exc}. Known apps: {[a[\"name\"] for a in apps]}')\n    raise","preventionTips":["Call list_apps first and use the exact returned 'name' or 'pid'.","Use 'pid:<pid>' for unambiguous targeting.","Retry after a short delay if the app was just launched and isn't registered yet."],"tags":["linux","at-spi","app","discovery","query"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}