Troubleshooting

Password fields (MacOS)

The overlay (and keybindings involving printable characters generally) will not respond when in a password field or other field marked as sensitive. This is not a bug, but a result of MacOS's 'Secure Input' mode, which prevents applications from reading keyboard input while in these fields. To continue using Mouseless, simply leave the field (e.g. by pressing Tab).

Hotkeys don't work after upgrading

At least one user has reported the following fix after upgrading to a new version of Mouseless:

  1. exit Mouseless
  2. delete the Accessibility permission for Mouseless
    • make SURE Mouseless isn't running while you do this -- MacOS tends to lock you out of keyboard and mouse input if you delete this permission from a running process
    • System Settings > Privacy and Security > Accessibility > select Mouseless and click the - button
  3. Re-add the permission (either via the + button or by restarting Mouseless)
  4. Restart Mouseless

Hotkeys don't work after a while (e.g. after lock screen)

This may be caused by a few different issues, one of which is MacOS getting stuck in 'Secure Input' mode. Espanso has a good explainer on this issue, as well as some potential workarounds to get un-stuck (the last resort is to log out your MacOS user and log back in).

This issue may be fixed / reduced in 0.4.0-preview.2, and it also has a button at the bottom of the config editor to check if the system is stuck in Secure Input mode.

SSL / Network proxies

Mouseless must use the network to start a trial and to validate licenses (purchased licenses store an offline license that must be refreshed at least every 30 days -- the program attempts to do this automatically).

If you are behind a corporate proxy (or if you have a custom SSL certificate for other reasons) and are seeing SSL errors on startup, you can use the following procedure to fix these errors, while we explore ways to prevent this extra legwork.

  1. Obtain the custom cert (.pem) file from your IT department
  2. Move/copy the .pem file to the Mouseless data dir, e.g.: $ cp cert.pem ~/Library/Containers/net.sonuscape.mouseless/Data/
  3. Open Mouseless via the command line like so: $ REQUESTS_CA_BUNDLE=~/Library/Containers/net.sonuscape.mouseless/Data/cert.pem open Mouseless.app

Simplified process (in preview)

Starting in v0.4.0-preview.2, this process should be greatly simplified: no more need to run from the terminal -- you will now be prompted to import the certificate on startup, and Mouseless should thereafter work whether you're on the network that requires the custom cert, or on a normal network.

At least one user, however, has gotten stuck in a loop where the cert is requested every startup, even after added (see issue 285). I haven't been able to reproduce this, so positive or negative feedback on this feature is appreciated!

BetterTouchTool conflicts

If you're having issues with BTT hotkeys erroneously triggering the Mouseless overlay, a user has kindly provided this config / example, which may help you keep the same BTT hotkey, but without triggering Mouseless.

Karabiner and other HID input-modifying apps

Apps that can prevent keypresses from being dispatched to the rest of the system (as Karabiner sometimes does when one of its keybindings is triggered) may cause Mouseless keybindings to trigger when not expected.

For example, if alt+F is assigned an action in Karabiner, and Alt tap is assigned to show overlay in Mouseless, karabiner might allow the alt press and release through to the rest of the system, but block the F press/release. If it's all pressed quickly enough, Mouseless might register this as Alt tap and display the overlay, as it has no visibility of the F key events.

So if you experience such issues, lowering the tap_threshold setting might help prevent most false triggers, otherwise you might need to adjust keybindings in one app or the other.

Note: In 0.4.0-preview.2 you can try changing the event tap location to see if this alleviates these conflicts. It also has a limited, privacy-conscious, display input mode that allows you to see which keyboard events Mouseless is receiving. Both of these options are found in the System / debug section at the bottom of the config editor.