Troubleshooting

Common issues and their solutions for MouseCross.

Installation Issues

Windows: "Windows Protected Your PC" Warning

Symptom: Windows SmartScreen blocks MouseCross from running.

Solution:

  1. Click "More info" on the warning dialog
  2. Click "Run anyway"
  3. MouseCross will launch normally

Why it happens: Unsigned applications trigger SmartScreen. Signed versions (coming soon) won't show this warning.

macOS: "App is Damaged and Can't Be Opened"

Symptom: macOS Gatekeeper prevents MouseCross from launching.

Solution:

xattr -cr /Applications/MouseCross.app

Then launch MouseCross again.

Alternative solution:

  1. Right-click (or Ctrl+click) MouseCross in Applications
  2. Select "Open"
  3. Click "Open" in the confirmation dialog

macOS: "Accessibility Permissions Required"

Symptom: Crosshair doesn't appear or track mouse movement.

Solution:

  1. Open System Settings
  2. Go to Privacy & Security → Accessibility
  3. Enable MouseCross in the list
  4. If MouseCross isn't listed, click the "+" button and add it
  5. Restart MouseCross

To verify permissions:

  1. Open System Settings → Privacy & Security → Accessibility
  2. MouseCross should be listed and have a checkmark
  3. If greyed out, try removing and re-adding

Crosshair Display Issues

Crosshair Not Visible

Possible causes and solutions:

1. Crosshair is Disabled

  • Press Ctrl+Alt+Shift+C to toggle it on
  • Check system tray/menu bar - icon should show "Active" state
  • Verify "Activate on startup" is enabled in Settings

2. Opacity Too Low

  • Open Settings
  • Check Opacity slider - should be at least 50%
  • Increase opacity to 80-100% for testing

3. Color Matches Background

  • Open Settings
  • Try a high-contrast color (bright red, cyan, lime green)
  • Or enable Inverted Mode for automatic contrast

4. Windows: Desktop Window Manager Not Running

  • Press Windows+R
  • Type services.msc and press Enter
  • Find "Desktop Window Manager Session Manager"
  • Ensure it's running and set to Automatic

5. macOS: Accessibility Permissions Missing

  • See "Accessibility Permissions Required" above

Crosshair Appears But Doesn't Move

Windows:

  1. Verify no other overlay applications are interfering
  2. Check if mouse drivers are up to date
  3. Try running as Administrator (right-click → Run as administrator)

macOS:

  1. Verify accessibility permissions are granted
  2. Check Console app for error messages
  3. Restart MouseCross

Crosshair Flickers or Stutters

Windows:

  • Update graphics drivers
  • Check if Windows is in Battery Saver mode (disable it)
  • Verify DWM (Desktop Window Manager) is enabled
  • Close other overlay applications (Discord overlay, OBS, etc.)

macOS:

  • Check Activity Monitor for high CPU usage from other apps
  • Update macOS to latest version
  • Try reducing opacity slightly

Crosshair Disappears on Certain Applications

Windows: Some fullscreen applications or games may prevent overlays:

  • Try running the application in windowed mode
  • Try running MouseCross as Administrator
  • Some games with anti-cheat may block overlays (this is expected)

macOS: Some fullscreen apps may hide the overlay:

  • Use the app in windowed mode instead
  • Check if the app has its own accessibility restrictions

Settings Issues

Settings Not Saving

Windows:

  • Ensure you click "Apply" or "OK" (not just closing the dialog)
  • Check registry permissions for HKEY_CURRENT_USER\Software\MouseCross
  • Try running as Administrator once to create registry keys

macOS:

  • Click "OK" to save (not just closing the window)
  • Check console for UserDefaults errors
  • Verify disk permissions are correct

Can't Change Hotkey

Windows:

  1. Click in the hotkey field
  2. Press your desired key combination
  3. Must include at least one modifier (Ctrl, Alt, Shift)
  4. Avoid system-reserved combinations

Invalid combinations will be rejected (e.g., Ctrl+Alt+Delete)

Restore Defaults Doesn't Work

Windows:

  1. Click "Restore Defaults" in Settings
  2. Must click "Apply" or "OK" to save
  3. If that fails, run kill_and_reset.bat to manually clear settings

macOS:

defaults delete com.mousecross.MouseCross

Then restart MouseCross.

Performance Issues

High CPU Usage

Normal usage: MouseCross should use <1% CPU on modern systems.

If CPU usage is high:

  1. Check if other applications are causing conflicts
  2. Update graphics drivers
  3. Reduce crosshair update frequency (if option available)
  4. Check for malware or other issues

High Memory Usage

Normal usage: ~10 MB RAM

If memory usage is high:

  • Restart MouseCross
  • Check for memory leaks (rare, please report if found)
  • Update to the latest version

Slow Startup

Windows:

  • Check if antivirus is scanning the executable
  • Move MouseCross.exe to an excluded location
  • Ensure SSD is not full (low disk space slows startup)

macOS:

  • Check Console app for errors during launch
  • Verify macOS is not indexing (Spotlight)

Hotkey Issues

Global Hotkey Not Working

Windows:

  1. Verify no other application is using the same hotkey
  2. Try a different key combination
  3. Check if hotkey registration shows errors in Event Viewer
  4. Restart MouseCross

macOS:

  1. Check System Settings → Keyboard → Keyboard Shortcuts
  2. Verify no conflict with system shortcuts
  3. Try a different combination
  4. Restart MouseCross

Hotkey Works Intermittently

Possible causes:

  • Other applications capturing the hotkey
  • Keyboard driver issues
  • System is under heavy load

Solutions:

  • Choose a unique key combination
  • Update keyboard drivers
  • Close conflicting applications

Auto-Start Issues

Auto-Start Not Working (Windows)

Verify registry entry:

  1. Press Windows+R
  2. Type regedit and press Enter
  3. Navigate to HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run
  4. Look for "MouseCross" entry
  5. Value should be the full path to MouseCross.exe

If missing:

  1. Open MouseCross Settings
  2. Enable "Start automatically with Windows"
  3. Click Apply/OK

If still not working:

  • Check if antivirus is blocking startup items
  • Verify Task Manager → Startup shows MouseCross as "Enabled"

Auto-Start Not Working (macOS)

Verify Login Items:

  1. Open System Settings
  2. Go to General → Login Items
  3. MouseCross should be in the list

If missing:

  1. Open MouseCross Settings
  2. Enable auto-start
  3. Click OK

If still not working:

  • Remove MouseCross from Login Items manually
  • Re-enable auto-start in MouseCross Settings
  • Check Console app for errors

Uninstallation Issues

Can't Delete MouseCross.exe (Windows)

Symptom: "File is in use" error when trying to delete.

Solution:

  1. Right-click system tray icon
  2. Select "Exit"
  3. Verify MouseCross.exe is not running in Task Manager
  4. Delete the file

If still locked:

  1. Restart Windows
  2. Delete before running MouseCross again

Registry Entries Remain (Windows)

After uninstalling, registry entries may remain:

To remove manually:

  1. Press Windows+R
  2. Type regedit
  3. Navigate to HKEY_CURRENT_USER\Software
  4. Delete the "MouseCross" key

Or use the included kill_and_reset.bat script.

Error Messages

"Failed to Create Overlay Window"

Windows:

  • Desktop Window Manager (DWM) must be running
  • Update graphics drivers
  • Ensure Windows Aero is enabled (Windows 7)
  • Try running as Administrator

"Accessibility Permissions Denied"

macOS:

  • Follow the accessibility permissions setup
  • Remove and re-add MouseCross in System Settings
  • Restart MouseCross after granting permissions

"Failed to Register Hotkey"

Possible causes:

  • Another application is using the same hotkey
  • System-reserved combination chosen
  • Hotkey registration service not available

Solutions:

  • Choose a different key combination
  • Close applications that might conflict
  • Restart Windows/macOS

Screen Reader Issues

Controls Not Being Announced (Windows)

NVDA:

  1. Ensure NVDA is running
  2. Press NVDA+N to verify
  3. Navigate to Settings dialog using Tab
  4. Verify "Line Width" slider announces correctly

If controls are silent:

  • Update NVDA to latest version
  • Check if NVDA is in sleep mode (NVDA+Shift+S)
  • Restart NVDA

JAWS:

  • Update to latest version
  • Verify JAWS is active in the application
  • Check JAWS cursor settings

Narrator:

  • Ensure Narrator is running (Windows+Ctrl+Enter)
  • Update Windows to latest version

Slider Values Not Announced

Verify:

  1. Focus the slider (Tab or Alt+shortcut)
  2. Press Arrow keys to adjust
  3. Value should be spoken

If values are silent:

  • Screen reader may need updating
  • Try a different screen reader for testing
  • Report the issue with your screen reader version

Reporting Issues

If you encounter an issue not covered here:

Information to Include

  1. Version: MouseCross version number (check About dialog)
  2. Platform: Windows version or macOS version
  3. Steps to reproduce: Detailed steps to trigger the issue
  4. Expected behavior: What should happen
  5. Actual behavior: What actually happens
  6. Screenshots: If applicable
  7. Error messages: Copy exact error text

Windows Diagnostic Information

Collect this information before reporting:

# Windows version
winver

# Check DWM status
Get-Service -Name "uxsms"

# Check registry key
reg query "HKCU\Software\MouseCross"

macOS Diagnostic Information

# macOS version
sw_vers

# Check Console for errors
# Open Console app, filter for "MouseCross"

# Check UserDefaults
defaults read com.mousecross.MouseCross

Where to Report

Getting Help

If you need additional assistance:

  1. Check the Installation Guide
  2. Review Settings Reference
  3. See Accessibility Features for screen reader help
  4. Check Keyboard Shortcuts for navigation help
  5. Report an issue on GitHub

Known Issues

Windows 7 Limitations

  • Some transparency features may not work on Windows 7
  • Ensure Windows Aero is enabled
  • Windows 10/11 recommended for full features

macOS Catalina and Earlier

  • Accessibility permission dialogs may differ
  • Some features may require macOS 11 Big Sur or later

macOS Sequoia: App Store Purchase Dialogs

Symptom: App Store install/purchase buttons disappear when MouseCross crosshair is active.

Cause: macOS Sequoia 15.3+ includes anti-clickjacking protection that hides purchase buttons when any overlay window is detected above them. This is an Apple security feature, not a MouseCross bug.

Solution: MouseCross shows a notification when you open the App Store while the crosshair is active, reminding you to toggle it off for purchases.

To complete App Store purchases:

  1. Toggle the crosshair off (use your hotkey or click the menu bar icon)
  2. Complete your App Store purchase
  3. Toggle the crosshair back on

The notification only appears once every 5 minutes to avoid being intrusive.

Note: This behavior may also affect other macOS system dialogs that require secure input (e.g., password prompts, Apple Pay). If you encounter issues with other system dialogs, temporarily disable the crosshair.

Multi-Monitor Issues

  • Crosshair may behave differently across monitors with different DPI settings
  • Per-monitor DPI awareness improvements coming in future updates

Next Steps