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 or --debug: enables verbose debug output, visible in both the log file and the terminal.

-p or --print-hid-events: 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

Conflicts with other utility apps

General hotkey conflicts (blocks or triggers)

If Mouseless blocks or triggers hotkeys for another app, or vice versa, changing the order they are launched in may help, or simply adjusting the keybindings in one app or the other.

On macOS, changing the event tap location may also alleviate these conflicts. It’s in the System / debug section at the bottom of the config editor.

Other app-specific workarounds follow in the sections below.

Unexpected triggering of tap commands

In some cases, Mouseless tap commands (e.g. show overlay) are triggered because another app’s hotkey blocks certain (but not all) keystrokes from reaching Mouseless.

If you experience such issues, lowering the tap_threshold setting might help prevent false triggers.

Karabiner example / explanation:

  • alt+F is assigned an action in Karabiner
  • Alt tap is assigned to show overlay in Mouseless
  • User presses alt+F quickly
  • Karabiner allows the alt press and release through, but blocks the F press and release
  • Mouseless sees an Alt tap (because it has no visibility of the F key events) and displays the overlay

Forthcoming solutions

Development is underway to resolve inter-app conflicts, including deep links and/or CLI-triggered Mouseless commands, which could provide a general solution to many of the conflicts.

Autohotkey

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

BetterTouchTool

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.

macOS

CLI 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

Important: If you have ever run the internal binary directly (e.g. /Applications/Mouseless.app/Contents/MacOS/mouseless), please ensure you have revoked the Accessibility permission from your terminal app, otherwise 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.

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

This may happen 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).

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

Windows

Overlay appears behind Taskbar, Task Manager, etc.

This is a current known limitation. Mouseless’ overlay does not (usually) appear above OS-native elements like the taskbar and start menu. It also does not work with Admin-privileged elements like the task manager.

A forthcoming fix is anticipated, and will likely require you to run Mouseless ‘as Administrator’ to work.

Linux

Blank Windows / dri_gbm.so

If windows appear empty, and/or you see errors like:

MESA-LOADER: failed to open dri: /usr/lib/gbm/dri_gbm.so: cannot open shared object file: No such file or directory (search paths /usr/lib/aarch64-linux-gnu/gbm, suffix _gbm)

Please try the following steps in order, checking if the issue is fixed after each one.

1. Ensure you have the drivers installed

# Ubuntu / Debian
sudo apt install libgl1-mesa-dri libgbm1

# Fedora
sudo dnf install mesa-dri-drivers mesa-libgbm

# Arch
sudo pacman -S mesa

2. Link driver paths

If the .so file still can’t be found by Mouseless, a symbolic link may fix the issue.

Note: you may need to replace /usr/lib/ with /usr/lib64, depending on your system. ARM users will need to replace x86_64 with aarch64.

  • First, find the file’s location:
find /usr/lib -name "dri_gbm.so" 2>/dev/null
  • Create the symlink between the folders:
# Replace '/usr/lib/gbm' with the path you found if different
sudo mkdir -p /usr/lib/x86_64-linux-gnu
sudo ln -s /usr/lib/gbm /usr/lib/x86_64-linux-gnu/

3. Last resort: Disable Compositing

If the blank windows still persist, you can do the following:

  • Solution: Use the --no-compositing CLI flag or WEBKIT_DISABLE_COMPOSITING_MODE=1 environment variable.
  • 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.

Overlay Size & Mouse Position

Mouseless does its best to automatically account for system display scaling to determine overlay size/position and mouse locations. Some users however, may need to do one of the following:

Starting in v0.5.0-preview.2

At the bottom of the config editor you’ll find these settings, and you can hover over their labels for full explanation of possible values.

  • Overlay scaling for fixing incorrectly sized or positioned overlays
  • Mouse scaling for fixing incorrect mouse click locations
  • Mouse screen offset scaling for fixing incorrect mouse click locations on multi-monitor setups (use ‘Mouse scaling’ for the leftmost monitor and this setting for the rest if needed)

The prior methods below are still available until these settings are battle-tested.

Prior methods (< v0.5.0-preview.2)

Overlay size/position:

  • 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:

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

Startup Errors

Segmentation Fault

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 developers of Mouseless are not liable for any issues that may arise from doing so.

‘Cannot Execute’ AppImage

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.

WebKit Error: “Failed to spawn child process”

Seen on Arch:

Failed to spawn child process “/usr/lib/webkit2gtk-4.1/WebKitNetworkProcess”

You may need to install webkit2gtk:

sudo pacman -S webkit2gtk-4.1

Then you may need to set up a symbolic link so Mouseless can find it:

sudo mkdir -p /usr/lib/x86_64-linux-gnu/
sudo ln -s /usr/lib/webkit2gtk-4.1 /usr/lib/x86_64-linux-gnu/

“Could not load a pixbuf” / GTK Icon Errors

Seen on some Arch-based systems (context):

(mouseless:49698): Gtk-WARNING **: 18:37:19.888: Could not load a pixbuf from /org/gtk/libgtk/icons/16x16/status/open-menu-symbolic.symbolic.png.
This may indicate that pixbuf loaders or the mime database could not be found.

You may have to do one or more of the following.

  • Ensure loaders are installed:
sudo pacman -S glycin-loaders gdk-pixbuf2
  • Set the $XDG_DATA_DIRS environment variable:
export XDG_DATA_DIRS=/usr/share/:/usr/local/share/:~/.local/share
./<mouseless_file>.AppImage
  • Extract and disable the bundled library:
# 1. Extract the AppImage
./<mouseless_file>.AppImage --appimage-extract
# 2. Disable the bundled pixbuf library
mv squashfs-root/usr/bin/_internal/libgdk_pixbuf-2.0.so.0 squashfs-root/usr/bin/_internal/libgdk_pixbuf-2.0.so.0.bak
#3. Run the extracted app
./squashfs-root/AppRun
  • Install a different pixbuf variant from AUR:
# Using an AUR helper (like yay):
yay -S gdk-pixbuf2-noglycin

# OR manually build/install 'gdk-pixbuf2-noglycin' from the AUR

Network Proxies / SSL

As of v0.4.2, Mouseless uses the system certificate store, which, for many corporate users, should eliminate the need to specify an SSL certificate to successfully activate and refresh 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. In the meantime, you can either:

  • A. In v0.4.3+: Use the Offline Licensing feature, available when app is first run or from the Mouseless menu (Tools > Offline Licensing)
  • B. Try the old SSL-cert instructions (below)

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