{"record":{"id":"629842b7ffb0a134","repo":"stablyai/orca","slug":"gdk-is-required-for-non-character-key-synthesis","errorCode":null,"errorMessage":"GDK is required for non-character key synthesis","messagePattern":"GDK is required for non-character key synthesis","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"native/computer-use-linux/runtime.py","lineNumber":930,"sourceCode":"\n\ndef key_name(raw):\n    aliases = {\n        \"return\": \"Return\", \"enter\": \"Return\", \"tab\": \"Tab\", \"escape\": \"Escape\", \"esc\": \"Escape\",\n        \"backspace\": \"BackSpace\", \"delete\": \"Delete\", \"space\": \"space\", \"left\": \"Left\", \"right\": \"Right\",\n        \"up\": \"Up\", \"down\": \"Down\", \"home\": \"Home\", \"end\": \"End\", \"insert\": \"Insert\",\n        \"pageup\": \"Page_Up\", \"page_up\": \"Page_Up\", \"pagedown\": \"Page_Down\", \"page_down\": \"Page_Down\",\n    }\n    return aliases.get(str(raw).lower(), str(raw))\n\n\ndef press_key(raw):\n    name = key_name(raw)\n    if len(name) == 1:\n        Atspi.generate_keyboard_event(0, name, Atspi.KeySynthType.STRING)\n        return\n    if Gdk is None:\n        raise RuntimeError(\"GDK is required for non-character key synthesis\")\n    Atspi.generate_keyboard_event(Gdk.keyval_from_name(name), None, Atspi.KeySynthType.PRESSRELEASE)\n\n\ndef hotkey(raw):\n    key_spec = re.sub(r\"(?i)commandorcontrol|cmdorctrl\", \"ctrl\", str(raw))\n    xdotool = shutil.which(\"xdotool\")\n    if xdotool:\n        subprocess.run([xdotool, \"key\", key_spec], check=True)\n        return\n    if \"+\" in key_spec:\n        raise RuntimeError(\"hotkey combinations require xdotool\")\n    press_key(key_spec)\n\n\ndef type_text(value):\n    Atspi.generate_keyboard_event(0, str(value), Atspi.KeySynthType.STRING)\n\n","sourceCodeStart":912,"sourceCodeEnd":948,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/native/computer-use-linux/runtime.py#L912-L948","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Install the GDK/GTK introspection packages (apt install python3-gi gir1.2-gtk-3.0 / dnf install python3-gobject gtk3).","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).","Restrict to single-character keys until GDK is available, if your workflow permits."],"exampleFix":"# before: missing GDK, pressing Return fails\n# after (shell):\nsudo apt install python3-gi gir1.2-gtk-3.0","handlingStrategy":"validation","validationCode":"import shutil\n\ndef can_press_named_key():\n    try:\n        from gi.repository import Gdk  # noqa\n        return True\n    except Exception:\n        return shutil.which(\"xdotool\") is not None\n\nif not can_press_named_key():\n    # restrict to single-character keys only","typeGuard":"def key_requires_gdk(name) -> bool:\n    return len(name) != 1","tryCatchPattern":"try:\n    run_operation(op)\nexcept RuntimeError as e:\n    if \"GDK is required\" in str(e):\n        # install gdk packages or skip the named key\n        pass\n    else:\n        raise","preventionTips":["Install python3-gi and a GDK provider (gir1.2-gtk-3.0) for named-key support.","Install xdotool so hotkey chords don't fall through to press_key.","Probe Gdk import at startup and warn users before they press special keys."],"tags":["environment","computer-use","keyboard","gdk","gtk","python"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}