You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
KeyError when pressing a physical key is pressed that isn't in the system keymap. #1850
If you have a system where a certain physical key is not present in the system KEYMAPS, then pressing that key throws a KeyError and causes the device to disconnect (tested only with Gemini PR, but may apply to other devices too).
To Reproduce
Steps to reproduce the behavior:
Create a system with a keymap like the following:
KEYMAPS= { "Gemini PR": { } }
# NOTE: this one maps no keys, however as long as there's at least one unmapped key, this will work.
Press an key that is not mapped in KEYMAPS.
Device will disconnect, throwing a stack trace like the following:
Exception in thread Thread-2-machine:
Traceback (most recent call last):
File "/home/runner/work/plover/plover/build/appimage/plover.AppDir/usr/lib/python3.13/threading.py", line 1041, in _bootstrap_inner
File "/home/runner/work/plover/plover/build/appimage/plover.AppDir/usr/lib/python3.13/site-packages/plover/machine/gemini_pr.py", line 56, in run
File "/home/runner/work/plover/plover/build/appimage/plover.AppDir/usr/lib/python3.13/site-packages/plover/machine/base.py", line 94, in _notify_keys
File "/home/runner/work/plover/plover/build/appimage/plover.AppDir/usr/lib/python3.13/site-packages/plover/machine/keymap.py", line 164, in keys_to_actions
KeyError: '#1'
Expected behavior
Most users or system developers probably don't expect a device to disconnect because they pressed an unmapped key. This can be an error in the system, however the documentation here doesn't explicitly say you have to map all keys, and use no-op for keys that aren't used by the system. It only says you can use no-op.
There's multiple solutions here:
Automatically map all unmapped to no-op.
State in the documentation that all keys must be mapped. Ideally there should be a run-time check when loading a system that refuses to load it if this invariant isn't upheld.
I prefer solution (1), as it makes it less annoying (and if, for whatever reason, a newer version of a protocol gains more keys, then you don't have to go modify every custom keymap).
changed the title [-]`KeyError` when pressing an unmapped key.[/-][+]`KeyError` when pressing a physical key is pressed that isn't in the system keymap.[/+]on Jun 16, 2026
Activity
[-]`KeyError` when pressing an unmapped key.[/-][+]`KeyError` when pressing a physical key is pressed that isn't in the system keymap.[/+]toyboot4e commentedon Jul 21, 2026
📝 The user is given WARNING on startup or when applying the mapping if any key is unbound:
I suggest solution 3: treat those unbound keys as no-op. I will send a small PR for this change.