Skip to content

KeyError when pressing a physical key is pressed that isn't in the system keymap. #1850

Closed

Description

@zipsegv

Describe the bug

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:

  1. 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.
  1. Press an key that is not mapped in KEYMAPS.
  2. 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:

  1. Automatically map all unmapped to no-op.
  2. 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).

Operating system

  • OS: Fedora 42
  • Plover Version: 5.3.0

I'm sure this is replicable on any system though.

Activity

  1. 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
  2. toyboot4e commented on Jul 21, 2026

    @toyboot4e
    Contributor

    📝 The user is given WARNING on startup or when applying the mapping if any key is unbound:

    Image

    I suggest solution 3: treat those unbound keys as no-op. I will send a small PR for this change.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions