{"record":{"id":"7a2899aeb6aa23dc","repo":"stablyai/orca","slug":"linux-computer-use-requires-an-active-desktop-sess","errorCode":null,"errorMessage":"Linux computer use requires an active desktop session; missing {missing}","messagePattern":"Linux computer use requires an active desktop session; missing (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"native/computer-use-linux/runtime.py","lineNumber":75,"sourceCode":"    width: float\n    height: float\n\n    def to_json(self):\n        return {\"x\": self.x, \"y\": self.y, \"width\": self.width, \"height\": self.height}\n\n\ndef attempt(fn, fallback=None):\n    try:\n        value = fn()\n        return fallback if value is None else value\n    except Exception:\n        return fallback\n\n\ndef ensure_desktop_bus():\n    missing = [name for name in (\"XDG_RUNTIME_DIR\", \"DBUS_SESSION_BUS_ADDRESS\") if not os.environ.get(name)]\n    if missing:\n        raise RuntimeError(\"Linux computer use requires an active desktop session; missing \" + \", \".join(missing))\n\n\ndef desktop_root():\n    return Atspi.get_desktop(0)\n\n\ndef children(node):\n    count = int(attempt(node.get_child_count, 0) or 0)\n    for index in range(count):\n        child = attempt(lambda i=index: node.get_child_at_index(i))\n        if child is not None:\n            yield index, child\n\n\ndef text_attr(node, getter):\n    return str(attempt(getter, \"\") or \"\")\n\n","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/native/computer-use-linux/runtime.py#L57-L93","documentation":"Raised by ensure_desktop_bus() (runtime.py:72-75) at process startup (main, line 1144) when either XDG_RUNTIME_DIR or DBUS_SESSION_BUS_ADDRESS is unset in os.environ. The Linux AT-SPI bridge needs an active D-Bus session bus to reach the accessibility registry; without these env vars there is no bus address to connect to and Atspi.get_desktop(0) would fail opaquely. The error lists exactly which vars are missing.","triggerScenarios":"Process launched without an inherited desktop session: SSH non-interactive shell (no D-Bus address exported), a systemd service unit without User=/environment, a Docker/container run without --session, or a cron-launched job. Any context where XDG_RUNTIME_DIR (typically /run/user/<uid>) and DBUS_SESSION_BUS_ADDRESS (unix:path=...) are not in the environment.","commonSituations":"Running the bridge over SSH without forwarding the session bus; invoking runtime.py from a service/daemon context; containerized execution that didn't source the user's dbus-session info; headless servers with no graphical session at all.","solutions":["Run the bridge inside the target user's graphical session so the env is inherited (graphical terminal, autostart .desktop).","For SSH: export DBUS_SESSION_BUS_ADDRESS and XDG_RUNTIME_DIR from the running session (e.g., source ~/.dbus/session-bus/* or use dbus-update-activation-environment).","For systemd services, set Environment=XDG_RUNTIME_DIR=/run/user/%U and ensure the user session bus is running (PAM systemd-logind).","If no graphical session exists, start one (loginctl enable-linger + a display) — AT-SPI requires a real desktop."],"exampleFix":"# before — launched from a context without session env\npython3 runtime.py op.json  # fails: missing XDG_RUNTIME_DIR, DBUS_SESSION_BUS_ADDRESS\n\n# after — import the running session's env\nexport $(grep -z DBUS_SESSION_BUS_ADDRESS /proc/$(pgrep -u $UID gnome-shell | head -1)/environ | tr -d '\\0')\nexport XDG_RUNTIME_DIR=/run/user/$UID\npython3 runtime.py op.json","handlingStrategy":"validation","validationCode":"# Validate env before launching the bridge\nimport os\nmissing = [n for n in ('XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS') if not os.environ.get(n)]\nif missing:\n    raise SystemExit(f'Cannot run Linux computer-use: missing {missing}. '\n                     f'Run inside the target user graphical session or export the env.')","typeGuard":"def has_desktop_bus_env() -> bool:\n    return bool(os.environ.get('XDG_RUNTIME_DIR')) and bool(os.environ.get('DBUS_SESSION_BUS_ADDRESS'))","tryCatchPattern":"try:\n    ensure_desktop_bus()\nexcept RuntimeError as exc:\n    if 'active desktop session' in str(exc):\n        # surface to caller with the missing-vars list and exit gracefully\n        print(json.dumps({'ok': False, 'error': str(exc), 'hint': 'run inside a graphical session'}))\n        sys.exit(1)\n    raise","preventionTips":["Run the bridge inside the target user's graphical session so env is inherited.","For SSH/systemd contexts, export XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS from the running session.","Add a preflight env check in the orchestrator that invokes runtime.py to fail fast with actionable guidance."],"tags":["linux","dbus","environment","at-spi","session"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}