stablyai/orca · error · RuntimeError

GDK is required for non-character key synthesis

Error message

GDK is required for non-character key synthesis

What it means

Raised by press_key (runtime.py:930) when the resolved key name has length > 1 (i.e. it is a named/special key, not a single character) and the GDK bindings (Gdk) are None — meaning the gi.repository.Gdk import failed at module load. Single-character keys are typed via AT-SPI STRING synthesis and never hit this; only named keys (Return, Tab, F1, etc.) require GDK keyval lookup.

Source

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

def key_name(raw):
    aliases = {
        "return": "Return", "enter": "Return", "tab": "Tab", "escape": "Escape", "esc": "Escape",
        "backspace": "BackSpace", "delete": "Delete", "space": "space", "left": "Left", "right": "Right",
        "up": "Up", "down": "Down", "home": "Home", "end": "End", "insert": "Insert",
        "pageup": "Page_Up", "page_up": "Page_Up", "pagedown": "Page_Down", "page_down": "Page_Down",
    }
    return aliases.get(str(raw).lower(), str(raw))


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)

View on GitHub (pinned to 1136503c6a)

Solutions

1. Install the GDK/GTK introspection packages (apt install python3-gi gir1.2-gtk-3.0 / dnf install python3-gobject gtk3).
2. Install xdotool so hotkey() takes the xdotool branch and never falls through to press_key for combinations (note: press_key for single named keys still needs GDK).
3. Restrict to single-character keys until GDK is available, if your workflow permits.

Example fix

# before: missing GDK, pressing Return fails
# after (shell):
sudo apt install python3-gi gir1.2-gtk-3.0

import shutil

def can_press_named_key():
    try:
        from gi.repository import Gdk  # noqa
        return True
    except Exception:
        return shutil.which("xdotool") is not None

if not can_press_named_key():
    # restrict to single-character keys only

def key_requires_gdk(name) -> bool:
    return len(name) != 1

try:
    run_operation(op)
except RuntimeError as e:
    if "GDK is required" in str(e):
        # install gdk packages or skip the named key
        pass
    else:
        raise

When it happens

Trigger: press_key or hotkey (when xdotool is absent and the spec has no '+') is called for a named key like 'Return', 'Escape', 'F5', 'left' while Gdk failed to import (typical when python-gi/gobject-introspection and a GDK provider like gir1.2-gtk-3.0 are not installed).

Common situations: A headless or minimal container missing GTK introspection packages; a system where gi imports but Gdk specifically does not; an agent pressing special keys on a stripped-down install.

Related errors

• hotkey combinations require xdotool
• modified clicks require xdotool on an X11 session
• {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/629842b7ffb0a134. Report an issue: GitHub.