stablyai/orca · error · RuntimeError

hotkey combinations require xdotool

Error message

hotkey combinations require xdotool

What it means

Raised by hotkey (runtime.py:941) when the key spec contains '+' (a chord) and xdotool is not installed. For chords, the runtime cannot fall back to AT-SPI press_key (which handles only a single key), so it requires xdotool to issue the combination. Single-key specs without '+' would instead fall through to press_key.

Source

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

def press_key(raw):
    name = key_name(raw)
    if len(name) == 1:
        Atspi.generate_keyboard_event(0, name, Atspi.KeySynthType.STRING)
        return
    if Gdk is None:
        raise RuntimeError("GDK is required for non-character key synthesis")
    Atspi.generate_keyboard_event(Gdk.keyval_from_name(name), None, Atspi.KeySynthType.PRESSRELEASE)


def hotkey(raw):
    key_spec = re.sub(r"(?i)commandorcontrol|cmdorctrl", "ctrl", str(raw))
    xdotool = shutil.which("xdotool")
    if xdotool:
        subprocess.run([xdotool, "key", key_spec], check=True)
        return
    if "+" in key_spec:
        raise RuntimeError("hotkey combinations require xdotool")
    press_key(key_spec)


def type_text(value):
    Atspi.generate_keyboard_event(0, str(value), Atspi.KeySynthType.STRING)


def paste_text(value):
    text = str(value)
    previous = read_clipboard()
    try:
        write_clipboard(text)
        hotkey("ctrl+v")
        # Why: X11 paste consumers may read the selection after the key event
        # returns, so keep the pasted text as the owner briefly before restore.
        time.sleep(CLIPBOARD_PASTE_SETTLE_SECONDS)
    finally:
        if previous is not None:

View on GitHub (pinned to 1136503c6a)

Solutions

1. Install xdotool (apt install xdotool / dnf install xdotool) on an X11 session.
2. If only a single key is needed, send a key without '+' so it routes to press_key instead.
3. On Wayland, use a Wayland-native tool; xdotool chord synthesis is X11-only.

Example fix

// before: no xdotool, chord fails
{"tool":"hotkey","key":"ctrl+c"}
# after (shell):
sudo apt install xdotool

import shutil

def can_hotkey_chord():
    return shutil.which("xdotool") is not None

if "+" in key_spec and not can_hotkey_chord():
    raise EnvironmentError("install xdotool to use key chords")

import shutil

def supports_hotkey_chords() -> bool:
    return shutil.which("xdotool") is not None

try:
    run_operation(op)
except RuntimeError as e:
    if "hotkey combinations require xdotool" in str(e):
        # split chord into individual press_key calls as a fallback
        pass
    else:
        raise

When it happens

Trigger: Calling the 'hotkey' tool with operation['key'] like 'ctrl+c', 'alt+tab', 'shift+ctrl+t' on a host where shutil.which('xdotool') is None. cmdorctrl/cmdorctrl are normalized to ctrl earlier (runtime.py:935) so they don't change this outcome.

Common situations: Minimal/container environments without xdotool; Wayland-only systems where xdotool isn't useful; assuming AT-SPI can synthesize arbitrary chords (it cannot here).

Related errors

• modified clicks require xdotool on an X11 session
• GDK is required for non-character key synthesis
• {command[0]} failed to set clipboard
• paste_text requires wl-copy, xclip, or xsel
• {name} must be a positive number

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