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

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.

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:

  • 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, 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 }

SSL / Network proxies / Air-gapped machines

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 to enable network connectivity.

  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

Simplified process

On some systems, this process is now 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.

Note: We're working to bring this simplified process to all systems.

Web interface / Air-gapped machines

We are also aiming to implement a secure web interface for generating an offline license file by the end of September, which will allow activation/validation on air-gapped machines, or can be used for SSL issues if a custom cert is not available.