platform-known-issues.adoc

Hardware known issues

At the electric circuit layer of many keyboards, cost-saving measures can lead to key presses not registering when pressing multiple keys simultaneously. Usually this happens with at least 3 key presses. Kanata cannot fix this issue. You can work around it by avoiding the problem key combination, or using a different keyboard.

Platform-dependent known issues

Preface

This document contains a list of known issues which are unique to a given platform. The platform supported by the core maintainer (jtroo) are Windows 11 and Linux. Windows 10 is expected to work fine, but as Windows 10 end-of-support is approaching in 2025, jtroo no longer has any devices with it installed.

On Windows, there are two backing mechanisms that can be used for keyboard input/output and they have different issues. These will be differentiated by the words "LLHOOK" and "Interception", which map to the binaries kanata.exe and kanata_wintercept.exe respectively.

Windows 11 LLHOOK

• Some input key combinations (e.g. Win+L) cannot be intercepted before running their default action

  • jtroo#192

  • jtroo#428

• OS-level key remapping behaves differently vs. Linux or Interception

  • Does not affect winiov2 variant

  • jtroo#152

• Certain applications that also use the LLHOOK mechanism may not behave correctly

  • jtroo#55

  • jtroo#250

  • jtroo#430

  • espanso/espanso#1488

• AltGr / ralt / Right Alt can misbehave

  • https://github.com/jtroo/kanata/blob/main/docs/config.adoc#windows-only-windows-altgr

• NumLock state can mess with arrow keys in unexpected ways

  • Does not affect winiov2 variant

  • jtroo#78

  • jtroo#667

  • Workaround: use the correct numlock state

• Without process-unmapped-keys yes, using arrow keys without also having the shift keys in defsrc will break shift highlighting

  • Does not affect winiov2 variant

  • jtroo#858

  • Workaround: add shift keys to defsrc or use process-unmapped-keys yes in defcfg

Windows 11 Interception

• Sleeping your system or unplugging/replugging devices enough times causes inputs to stop working

  • oblitum/Interception#25

• Some less-frequently used keys are not supported or handled correctly

  • jtroo#127

  • jtroo#164

  • jtroo#425

  • jtroo#532

Linux

• Key repeats can occur when they normally wouldn’t in some cases

  • jtroo#422

  • jtroo#450

  • jtroo#1441

• Unicode support has varying success due to many applications not supporting the ibus input mechanism. Using xkb to map keys to unicode or using clipboard actions are more consistent solutions

  • jtroo#703

• Key actions can behave incorrectly due to the rapidity of key events

  • jtroo#733

  • jtroo#740

  • adjusting rapid-event-delay can potentially be a workaround

• Macro keys on certain gaming keyboards might stop being processed

  • Context: search for POTENTIAL PROBLEM - G-keys in the code.

  • Workaround: leave process-unmapped-keys disabled and explicitly map keys in defsrc instead

MacOS

• Mouse input processing requires Accessibility or Input Monitoring permission in System Settings > Privacy & Security