Skip to content

Troubleshooting

Jump to bottom
Quadstronaut edited this page Jun 7, 2026 · 1 revision

Troubleshooting

Windows: SmartScreen blocks the EXE

Symptom: "Windows protected your PC" dialog on first launch.

Cause: The binary is unsigned. Windows SmartScreen blocks unsigned executables from unknown publishers until an Authenticode certificate is in place.

Fix: Click More info → Run anyway.

This warning will disappear once the binary is signed with an Authenticode certificate. See CODE_SIGNING.md for the signing plan.

Windows: Location picker doesn't work / shows hook error

Symptom: The overlay appears but immediately shows "Hook install failed — see %APPDATA%\QuadClicker\picker.log" in red, or the picker fires at the wrong location.

Cause: The low-level mouse hook (SetWindowsHookEx(WH_MOUSE_LL)) failed to install. This can happen if:

  • The app is running without sufficient privileges on some configurations
  • A security product is blocking low-level hooks

Diagnosis: Open %APPDATA%\QuadClicker\picker.log — every step of the BeginPick → ShowOverlay → SetHook → HookCallback chain is logged there.

Fix: Try running the app as Administrator. If a security product (antivirus, EDR) is blocking hooks, add an exception for QuadClicker.

Windows: Hotkeys don't fire

Symptom: Pressing the configured hotkey does nothing when another window has focus.

Checks:

  1. Another application may have registered the same key combination. RegisterHotKey fails silently when a key is already taken. Try a different combination.
  2. Confirm the hotkey is saved — restart the app and verify the key appears in the hotkey field.
  3. Some virtual desktop or window manager software intercepts hotkeys before they reach applications.

Windows: Update check fails

Symptom: No update notification or "Update check failed" in the tray.

Cause: The update check requires an outbound HTTPS connection to api.github.com. Network failures are silently swallowed to avoid blocking launch.

Diagnosis: Run quadclicker --check-update from a terminal. It prints either "Update available: vX.Y.Z" or "Up to date (vX.Y.Z)" on success, or "Update check failed: " on error (exit 2).

Fix: Check your firewall or proxy settings. The app uses the system default HTTP client with no proxy configuration — if your environment requires a proxy, it needs to be configured at the OS level.

macOS: Accessibility permission not working

Status note: macOS has never been run. These steps are sourced from the implementation and Apple documentation.

Symptom: Global hotkeys don't fire.

Cause: NSEvent.addGlobalMonitorForEvents requires Accessibility permission (TCC: com.apple.private.accessibility.inspection). Without it, AXIsProcessTrusted() returns false and the hotkey monitor is not installed.

Fix:

  1. Open System Settings → Privacy & Security → Accessibility
  2. Click the lock icon and authenticate
  3. Find QuadClicker in the list and enable it, or click + to add it
  4. Relaunch QuadClicker

macOS: CGEventPost doesn't inject clicks

Status note: macOS has never been run.

Symptom: Clicking appears to start (status shows active) but no mouse events appear.

Cause: Same as above — Accessibility permission is also required for CGEventPost. An app without the permission can create events but the OS will not deliver them to other processes.

Fix: Grant Accessibility permission as above.

Linux: No clicks injected under X11

Symptom: QuadClicker runs without error but no click events appear.

Checks:

  1. Confirm you're on an X11 session: echo $DISPLAY should show something like :0. If empty, you're on a pure Wayland session.
  2. Confirm the XTest extension is available: xdpyinfo | grep XInputExtension (the extension is XTEST).
  3. Run with --rate 1000ms --stop-after-clicks 3 and watch the terminal — it prints click counts.

Linux: No clicks injected under Wayland

Symptom: QuadClicker runs without error but no clicks appear, or you get a runtime error about uinput.

Cause: Wayland click injection uses the uinput kernel interface and requires /dev/uinput access.

Fix:

# Check if /dev/uinput exists
ls -la /dev/uinput

# Add yourself to the input group (if the device exists but is permission-denied)
sudo usermod -aG input $USER
# Log out and back in for the group change to take effect

# If /dev/uinput doesn't exist, load the module
sudo modprobe uinput

If you're in a container or a restricted environment, uinput may not be available at all. In that case, use an X11 session.

Linux: Hotkeys don't work under Wayland

This is expected behavior. Global hotkeys are not supported under Wayland — see Hotkeys-and-Platform-Notes for the full explanation and workarounds.

Linux: Build fails — Qt6 not found

Symptom: CMake error: Could not find a configuration file for package "Qt6".

Fix (Ubuntu/Debian):

sudo apt install qt6-base-dev qt6-base-dev-tools qt6-tools-dev libqt6svg6-dev \
                 libxtst-dev libxss-dev libx11-dev libdbus-1-dev

libdbus-1-dev is usually pulled in transitively by qt6-base-dev — CI builds succeed without it.

Fix (Fedora):

sudo dnf install qt6-qtbase-devel qt6-qttools-devel \
                 libXtst-devel libXScrnSaver-devel libX11-devel

dbus-devel is typically pulled in transitively by qt6-qtbase-devel on Fedora.

If multiple Qt versions are installed, you may need to set Qt6_DIR explicitly:

cmake -B build -G Ninja -DQt6_DIR=/path/to/qt6/lib/cmake/Qt6 linux/

Linux: GUI doesn't render / crashes on launch

Symptom: The app exits immediately or shows a blank window.

Check display environment:

echo $DISPLAY       # should be :0 or similar for X11
echo $WAYLAND_DISPLAY  # wayland-0 or similar for Wayland

Under WSL2: WSLg must be active (requires Windows 11 or Windows 10 with WSLg update). Run wsl --update to ensure WSLg is installed, then open a new terminal.

Fallback: Set QT_QPA_PLATFORM=xcb to force X11 if Wayland auto-detection is causing issues:

QT_QPA_PLATFORM=xcb ./build/quadclicker

Clone this wiki locally