Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Troubleshooting

Debug modes

Running Mouseless from the command line with certain flags provides extra visibility into what’s happening under the hood.

-d: enables verbose debug output, visible in both the log file and the terminal.

-p: prints keyboard input and mouse output to the terminal (not logged to file). To prevent accidental exposure, the printing will automatically disable after 5 minutes. This mode gives visibility into whether Mouseless is receiving certain keyboard events and how it’s interpreting them.

Examples:

macOS

open -W --stdout $(tty) --stderr $(tty) --stdin $(tty) /Applications/Mouseless.app --args -d

Windows (using Powershell)

& 'C:\Program Files\Mouseless\mouseless.exe' -d

Linux

./<filename>.AppImage -d

macOS Input Issues

Important Security Advisory

On macOS, the only recommended way to run Mouseless from a terminal is with the open command (e.g. open -W --stdout $(tty) --stderr $(tty) --stdin $(tty) /Applications/Mouseless.app).

If you have ever run Mouseless from the terminal by executing the file inside the .app bundle directly (e.g. /Applications/Mouseless.app/Contents/MacOS/mouseless), please take a moment to ensure you have revoked the Accessibility permission from your terminal app(s). Leaving this permission enabled for a terminal app presents a security risk, as any program launched from that terminal could potentially read screen content or log keystrokes.

To check your settings:

  • Go to System Settings > Privacy & Security > Accessibility.
  • Review the list. If your terminal application (e.g., Terminal, iTerm2) is present, select it and click the minus (-) button to revoke the permission.

Password fields

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 on app startup

If you ever encounter an issue where hotkeys don’t work on app startup, these steps have proven to help in most cases:

  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 / active event tap
    • 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 stop working during app usage

There may be a chance that this happens due to MacOS getting stuck in ‘Secure Input’ mode. There is a Check Secure Input Status button at the bottom of the config editor to check if this is the cause.

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).

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.

General conflicts with other keyboard utility apps

Apps like Mouseless, Karabiner, etc. can suppress keypresses from being dispatched to the rest of the system. Depending on the configuration of other apps, some hotkeys 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.

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.

On macOS, you can try changing the event tap location to see if this alleviates these conflicts. It’s found in the System / debug section at the bottom of the config editor.

Windows Input Issues

Autohotkey

To use a Windows key tap without triggering the start menu, use this: ~LWin::vkE8 (see reddit thread)

Linux - Common Issues

Blank Windows

This is likely the result of GPU/driver compatibility issues.

  • Solution: You can use the --no-compositing CLI flag or WEBKIT_DISABLE_COMPOSITING_MODE=1 environment variable to fix this
  • Side effect: When using this mode, the overlay may not clear its draw buffer correctly, causing highlights and subgrids to stay visible when they shouldn’t. Background and highlights accumulate opacity, but typically clear approximately every 5 uses of the overlay.
  • Workaround: There is a minimal_background style preset that helps alleviate the opacity buildup side effect.

I have a suspicion/hope that this issue might be resolvable with proprietary drivers (see solution/disclaimer in the “Segmentation Fault” section just below). If you find this to be the case, please let me know!

Segmentation Fault on Startup

Observed on Linux Mint 22: the app crashes with a ‘segmentation fault’ error in the terminal on startup.

  • Solution: You may find that installing proprietary drivers (as opposed to ‘Mesa’ drivers) solves the issue for you – see this user-provided guide for more info / instructions.
  • Disclaimer: update drivers at your own risk. The creators of Mouseless are not liable for any issues that may arise from doing so.

‘Cannot Execute’ AppImage errors

If, when running Mouseless, you see a terminal message like: cannot execute: required file not found

Or the more specific error: dlopen(): error loading libfuse.so.2: cannot open shared object file

…you are likely missing the FUSE 2 library, which is no longer pre-installed on many modern distributions.

Here are the common packages needed to run AppImages:

  • On Fedora:

    sudo dnf install fuse-libs

  • On Debian 13+ / Ubuntu 24+:

    sudo apt install libfuse2t64

  • On Debian 12 / Ubuntu 22:

    sudo apt install libfuse2

See issue #445 for context.

Overlay Size

Mouseless does its best to automatically determine and account for system DPI scaling to correctly size and position the overlay(s). Some users however, may need to do one of the following:

Starting in v0.5.0-preview.2: you can use the overlay_scaling setting at the bottom of the config editor to adjust the overlay size. The prior method below is still available until overlay_scaling is battle-tested.

Prior method (< v0.5.0-preview.2):

  • Use the --dpi-scale CLI option to force a certain scale. The value is your system’s DPI divided by 96 (the default). For example, for a system with 192 DPI, use --dpi-scale 2.0.
  • Use --dpi-scale 1 to counteract the effects of the automatic process

Mouse Position

If you find that mouse click positions don’t line up with the overlay:

Starting in v0.5.0-preview.2: you can use the mouse_scaling and mouse_screen_offset_scaling settings at the bottom of the config editor to adjust mouse click locations. The prior method below is still available until these settings are battle-tested.

Prior method (< v0.5.0-preview.2): you can currently use the debug options field (at bottom of config editor) to enter JSON to fix this (adjust values as needed):

{ "mouse_screen_position_mult": 1, "mouse_screen_size_mult": 1.25 }

Network Proxies / SSL Issues

As of v0.4.2, Mouseless now uses the system certificate store, which, for many corporate users, should eliminate the need to specify an SSL certificate to successfully activate / validate your license.

If you still have SSL, proxy authentication, or other network-related issues, please contact support and we will work on getting Mouseless to ‘just work’ in all cases. The old instructions may allow you to use Mouseless in the meantime:

Specifying a Custom Cert (Prior Method)

  1. Obtain the custom cert (.pem) file from your IT department
  2. On macOS, 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:
  • macOS
REQUESTS_CA_BUNDLE=~/Library/Containers/net.sonuscape.mouseless/Data/cert.pem open Mouseless.app
  • Windows (powershell)
$env:REQUESTS_CA_BUNDLE="path\to\cert.pem"; & 'C:\Program Files\Mouseless\mouseless.exe'
  • Linux
REQUESTS_CA_BUNDLE=path/to/cert.pem ./<filename>.AppImage

Air-gapped / Networkless Activation

For those who use an air-gapped machine, or whose organization has strict network restrictions, an offline licensing procedure is available (as of v0.4.3). Simply choose the “Offline Licensing” option in the introductory dialogs before activation, or after activation, from the Mouseless menu (Tools -> Offline licensing).