= 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
** https://github.com/jtroo/kanata/issues/192
** https://github.com/jtroo/kanata/discussions/428
* OS-level key remapping behaves differently vs. Linux or Interception
** Does not affect winiov2 variant
** https://github.com/jtroo/kanata/issues/152
* Certain applications that also use the LLHOOK mechanism may not behave correctly
** https://github.com/jtroo/kanata/issues/55
** https://github.com/jtroo/kanata/issues/250
** https://github.com/jtroo/kanata/issues/430
** https://github.com/espanso/espanso/issues/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
** https://github.com/jtroo/kanata/issues/78
** https://github.com/jtroo/kanata/issues/667
** Workaround: use the correct https://github.com/jtroo/kanata/discussions/354[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
** https://github.com/jtroo/kanata/issues/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
** https://github.com/oblitum/Interception/issues/25
* Some less-frequently used keys are not supported or handled correctly
** https://github.com/jtroo/kanata/issues/127
** https://github.com/jtroo/kanata/issues/164
** https://github.com/jtroo/kanata/issues/425
** https://github.com/jtroo/kanata/issues/532
== Linux
* Key repeats can occur when they normally wouldn't in some cases
** https://github.com/jtroo/kanata/discussions/422
** https://github.com/jtroo/kanata/issues/450
** https://github.com/jtroo/kanata/issues/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
** https://github.com/jtroo/kanata/discussions/703
* Key actions can behave incorrectly due to the rapidity of key events
** https://github.com/jtroo/kanata/discussions/733
** https://github.com/jtroo/kanata/issues/740
** adjusting https://github.com/jtroo/kanata/blob/main/docs/config.adoc#rapid-event-delay[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
link:../src/kanata/mod.rs[the code].
** Workaround: leave `process-unmapped-keys` disabled
and explicitly map keys in `defsrc` instead
== MacOS
* Only left, right, and middle mouse buttons are implemented for clicking
* Mouse input processing is not implemented, e.g. putting `mlft` into `defsrc` does nothing
