Troubleshooting

This page covers some general and platform-specific problems. Also see:

• App conflicts & compatibility – if another utility app is blocking or triggering hotkeys
• Command line & debug options – for debug output and rendering overrides

Reducing overlay lag

If the overlay feels sluggish, try some or all of these settings to make it more responsive:

highlight animation (ms): 0
always show subgrid: off
grid line style: lines
text shadow opacity: 0
move system cursor with virtual: off

If you are on Linux, you can also try changing the overlay_renderer (see Command line & debug options).

macOS

Startup issues: No windows or status icon visible, or hotkeys don’t work

If you ever encounter these startup issues, these steps have proven to help in most cases:

1. Exit Mouseless (via Activity Monitor if status icon is not visible)
2. Go to System Settings > Privacy and Security > Accessibility
3. Delete the Accessibility permission for Mouseless, if present
   • 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
   • select Mouseless and click the - button
4. Re-add the permission
   • Click the + button, add /Applications/Mouseless.app
   • Make sure Mouseless is toggled ON
5. Restart Mouseless

Hotkeys stop working during app usage

This may happen due to MacOS getting stuck in ‘Secure Input’ mode. Check the Mouseless icon in the status bar – if there’s a lock icon on it, the system is 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).

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.

For Mouseless to show the overlay above Start Menu, task manager, etc., you must:

• choose to install for ‘all users’
• install to a privileged location like Program Files (default)

This requires admin privileges during the installation process only, not when actually running Mouseless.

The installer provides an option to uninstall other/prior installations at different locations, checked by default. Your user data is not affected by the uninstallation.

For the portable version or non-privileged install locations, Mouseless makes a best effort to show above the taskbar, but is not guaranteed to work in all situations.

WebView2 Runtime

Older versions of Windows may need the WebView2 runtime added. The Mouseless installer installs it if it’s missing, which requires internet access.

On a machine without internet access, either:

• Install the runtime with Microsoft’s “Evergreen Standalone Installer”, from the link above, OR

• In 1.1 preview: put a Fixed Version runtime beside Mouseless:

  1. Download the x64 Fixed Version package (a .cab file) from the link above
  2. Extract it, e.g. expand Microsoft.WebView2.FixedVersionRuntime.<version>.x64.cab -F:* C:\temp
  3. Rename the extracted folder (the one containing msedgewebview2.exe) to WebView2Runtime
  4. Move it into the folder containing mouseless.exe, so that msedgewebview2.exe ends up at e.g.:
     • C:\Program Files\Mouseless\WebView2Runtime\msedgewebview2.exe (installed for all users)
     • mouseless\WebView2Runtime\msedgewebview2.exe in the extracted folder (portable)

  Mouseless uses a runtime in that folder in place of an installed one. If the WEBVIEW2_BROWSER_EXECUTABLE_FOLDER environment variable is set, the runtime it points to is used instead.

Linux

Overlay / Mouse Position & Scale

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 make manual adjustments.

At the bottom of the config editor (in 1.1 preview: on the System / Debug page) 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)

Further, if you find that the overlay position needs manual adjustment, you can set the overlay_offset debug option.

Overlay / Window rendering issues

Some graphics cards / environments have issues rendering webviews with transparency, or at all.

If you encounter issues with transparency, set overlay_renderer to cairo to force the cairo-backed overlay (default when NVIDIA GPU is detected).

If windows appear blank and the overlay seems to not show at all, set use_dmabuf to false to force DMABUF rendering off for webviews (default when NVIDIA GPU is detected).

Both can be set as a command line flag or a config field, and both are described in Command line & debug options.

Overlay fades/animates in slowly (Wayland)

On Wayland compositors that support wlr-layer-shell, the overlay is a layer-shell surface with the namespace mouseless-overlay. If your compositor animates layer surfaces, disable animations for that namespace so the overlay appears instantly. E.g. on Hyprland:

layerrule = noanim, mouseless-overlay