stablyai/orca · critical · RuntimeError

Linux computer use requires an active desktop session; missi

Error message

Linux computer use requires an active desktop session; missing {missing}

What it means

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.

Source

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

    width: float
    height: float

    def to_json(self):
        return {"x": self.x, "y": self.y, "width": self.width, "height": self.height}


def attempt(fn, fallback=None):
    try:
        value = fn()
        return fallback if value is None else value
    except Exception:
        return fallback


def ensure_desktop_bus():
    missing = [name for name in ("XDG_RUNTIME_DIR", "DBUS_SESSION_BUS_ADDRESS") if not os.environ.get(name)]
    if missing:
        raise RuntimeError("Linux computer use requires an active desktop session; missing " + ", ".join(missing))


def desktop_root():
    return Atspi.get_desktop(0)


def children(node):
    count = int(attempt(node.get_child_count, 0) or 0)
    for index in range(count):
        child = attempt(lambda i=index: node.get_child_at_index(i))
        if child is not None:
            yield index, child


def text_attr(node, getter):
    return str(attempt(getter, "") or "")

View on GitHub (pinned to 1136503c6a)

Solutions

1. Run the bridge inside the target user's graphical session so the env is inherited (graphical terminal, autostart .desktop).
2. 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).
3. For systemd services, set Environment=XDG_RUNTIME_DIR=/run/user/%U and ensure the user session bus is running (PAM systemd-logind).
4. If no graphical session exists, start one (loginctl enable-linger + a display) — AT-SPI requires a real desktop.

Example fix

# before — launched from a context without session env
python3 runtime.py op.json  # fails: missing XDG_RUNTIME_DIR, DBUS_SESSION_BUS_ADDRESS

# after — import the running session's env
export $(grep -z DBUS_SESSION_BUS_ADDRESS /proc/$(pgrep -u $UID gnome-shell | head -1)/environ | tr -d '\0')
export XDG_RUNTIME_DIR=/run/user/$UID
python3 runtime.py op.json

# Validate env before launching the bridge
import os
missing = [n for n in ('XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS') if not os.environ.get(n)]
if missing:
    raise SystemExit(f'Cannot run Linux computer-use: missing {missing}. '
                     f'Run inside the target user graphical session or export the env.')

def has_desktop_bus_env() -> bool:
    return bool(os.environ.get('XDG_RUNTIME_DIR')) and bool(os.environ.get('DBUS_SESSION_BUS_ADDRESS'))

try:
    ensure_desktop_bus()
except RuntimeError as exc:
    if 'active desktop session' in str(exc):
        # surface to caller with the missing-vars list and exit gracefully
        print(json.dumps({'ok': False, 'error': str(exc), 'hint': 'run inside a graphical session'}))
        sys.exit(1)
    raise

When it happens

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

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

Related errors

• Wayland GPU sandbox validation requires a Wayland session.
• No top-level AT-SPI window is available for {app}
• 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/7a2899aeb6aa23dc. Report an issue: GitHub.