Troubleshooting Guide

Common issues and solutions for QMKonnect across different platforms.

General Issues

QMKonnect Won’t Start

Symptoms: App doesn’t start or exits right away

Solutions:

  1. Check configuration file: 
    qmkonnect -c  # Create default config
qmkonnect -v  # Run with verbose output
  2. Check dependencies:
    • Make sure required libraries are installed
    • Check system compatibility
  3. Run with debug output: 
    qmkonnect --debug
  4. Check permissions:
    • Linux: User in input and plugdev groups
    • macOS: Accessibility permissions granted
    • Windows: Run as Administrator if needed

Keyboard Not Detected

Symptoms: QMKonnect runs but doesn’t communicate with keyboard

Diagnosis:

# Test keyboard connection
qmkonnect --test-connection

# List available HID devices
# Linux:
ls -la /dev/hidraw*
cat /sys/class/hidraw/hidraw*/device/uevent

# Windows:
# Use Device Manager to check HID devices

# macOS:
system_profiler SPUSBDataType | grep -i keyboard

Solutions:

  1. Verify keyboard configuration:
    • Check vendor_id and product_id in config
    • Ensure Raw HID is enabled in QMK firmware
    • Confirm qmk-notifier module is included
  2. Check QMK firmware: 
    // In rules.mk
RAW_ENABLE = yes
   
// In config.h
#define RAW_USAGE_PAGE 0xFF60
#define RAW_USAGE_ID   0x61
  3. Permission issues (Linux): 
    # Add user to groups
sudo usermod -a -G input,plugdev $USER
   
# Install udev rules
sudo cp packaging/linux/udev/99-qmkonnect.rules.template /etc/udev/rules.d/99-qmkonnect.rules
sudo udevadm control --reload && sudo udevadm trigger

Window Detection Not Working

Symptoms: QMKonnect runs but doesn’t detect window changes

Platform-specific solutions:

Windows 

# Check if running as tray app
qmkonnect --tray-app

# Verify window hooks are working
qmkonnect -v  # Look for window change events

Linux 

# Check Hyprland integration
echo $HYPRLAND_INSTANCE_SIGNATURE

# Test Hyprland socket
socat -u UNIX-CONNECT:/tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock -

Note: Only Hyprland is supported on Linux. Other window managers are not supported yet. Please contribute support for your window manager!

macOS

  1. Grant Accessibility permissions:
    • System Preferences → Security & Privacy → Privacy
    • Select “Accessibility”
    • Add QMKonnect to allowed applications
  2. Test window detection: 
    ./QMKonnect.app/Contents/MacOS/qmkonnect -v

Platform-Specific Issues

Windows Issues

System Tray Icon Missing

Solutions:

  1. Check if running as tray app: 
    qmkonnect --tray-app
  2. Restart Windows Explorer: 
    taskkill /f /im explorer.exe
start explorer.exe
  3. Check system tray settings:
    • Settings → Personalization → Taskbar
    • Select which icons appear on taskbar

Multiple Instances Running

Symptoms: Multiple QMKonnect processes in Task Manager

Solutions:

  1. Kill all instances: 
    taskkill /f /im qmkonnect.exe
  2. Start single instance: 
    qmkonnect --tray-app
  3. Check startup folder for duplicates:
    • %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup

Permission Errors

Solutions:

  1. Run as Administrator
  2. Check Windows Defender exclusions
  3. Verify antivirus isn’t blocking the application

Linux Issues

Systemd Service Fails

Check service status:

systemctl --user status qmkonnect
journalctl --user -u qmkonnect -f

Common fixes:

  1. Service file issues: 
    # Reinstall service file
curl https://raw.githubusercontent.com/dabstractor/qmkonnect/main/packaging/linux/systemd/qmkonnect.service.template | tee ~/.config/systemd/user/qmkonnect.service
   
systemctl --user daemon-reload
systemctl --user enable --now qmkonnect
  2. Binary path issues: 
    # Verify binary location
which qmkonnect
   
# Update service file if needed
systemctl --user edit qmkonnect

Hyprland Integration Issues

Check Hyprland socket:

# Verify socket exists
ls -la /tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/

# Test socket communication
socat -u UNIX-CONNECT:/tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock - | head -10

Solutions:

  1. Socket permission issues: 
    # Check socket permissions
ls -la /tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock
   
# Restart Hyprland if needed

Note: Only Hyprland is supported on Linux. Other window managers are not supported yet. Please contribute support for your window manager!

macOS Issues

Accessibility Permissions

Grant permissions:

  1. System Preferences → Security & Privacy → Privacy
  2. Select “Accessibility” from left panel
  3. Click lock to make changes
  4. Add QMKonnect to allowed applications

Verify permissions:

# Check current permissions
sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db "SELECT * FROM access WHERE service='kTCCServiceAccessibility';"

Application Bundle Issues

Solutions:

  1. Rebuild application bundle: 
    cd packaging/macos
./build.sh
  2. Check code signing: 
    codesign -v QMKonnect.app
  3. Reset application permissions: 
    tccutil reset Accessibility com.yourcompany.qmkonnect

Configuration Issues

Invalid Configuration File

Symptoms: Configuration errors on startup

Solutions:

  1. Validate TOML syntax: 
    # Use online TOML validator or
python3 -c "import toml; toml.load('config.toml')"
  2. Reset to defaults: 
    # Backup current config
cp ~/.config/qmk-notifier/config.toml ~/.config/qmk-notifier/config.toml.bak
   
# Create new default config
qmkonnect -c
  3. Check file permissions: 
    ls -la ~/.config/qmk-notifier/config.toml
chmod 644 ~/.config/qmk-notifier/config.toml

Wrong Keyboard IDs

Find correct IDs:

Using QMK Configuration 

// Check your QMK config.h
#define VENDOR_ID    0xFEED
#define PRODUCT_ID   0x0000

Using System Tools 

# Linux
lsusb | grep -i keyboard
cat /sys/class/hidraw/hidraw*/device/uevent | grep -E "HID_ID|HID_NAME"

# macOS
system_profiler SPUSBDataType | grep -A 10 -B 10 -i keyboard

# Windows PowerShell
Get-WmiObject -Class Win32_USBHub | Where-Object {$_.Name -like "*keyboard*"}

Performance Issues

High CPU Usage

Diagnosis:

# Monitor CPU usage
top -p $(pgrep qmkonnect)

# Check polling interval
qmkonnect -v  # Look for timing information

Solutions:

  1. Increase polling interval: 
    [window_detection]
poll_interval = 200  # Increase from default 100ms
  2. Use application filtering: 
    [window_detection]
include_apps = ["code", "firefox", "terminal"]  # Only monitor specific apps
  3. Check for infinite loops: 
    qmkonnect --debug  # Look for repeated events

Memory Leaks

Monitor memory usage:

# Linux
ps aux | grep qmkonnect
valgrind --leak-check=full qmkonnect

# macOS
leaks qmkonnect

# Windows
# Use Task Manager or Process Explorer

Communication Issues

Data Not Reaching Keyboard

Debug communication:

# Show what's being sent
qmkonnect --dry-run

# Test with minimal data
qmkonnect --debug

Check QMK side:

// Add debug output to QMK
#ifdef CONSOLE_ENABLE
void qmk_notifier_notify(const char* app_class, const char* window_title) {
    printf("Received: app='%s', title='%s'\n", app_class, window_title);
}
#endif

Raw HID Issues

Verify Raw HID setup:

  1. QMK firmware: 
    # In rules.mk
RAW_ENABLE = yes
  2. Test Raw HID: 
    # Linux - test hidraw device
echo "test" > /dev/hidraw0
   
# Check if device accepts data
qmkonnect --test-connection

Getting Help

Collecting Debug Information

When reporting issues, include:

  1. System information: 
    # Linux
uname -a
lsb_release -a
   
# macOS
sw_vers
   
# Windows
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
  2. QMKonnect version: 
    qmkonnect --version
  3. Debug output: 
    qmkonnect --debug > debug.log 2>&1
  4. Configuration file: 
    cat ~/.config/qmk-notifier/config.toml

Where to Get Help

Creating Bug Reports

Include:

  • Operating system and version
  • QMKonnect version
  • Steps to reproduce
  • Expected vs actual behavior
  • Debug logs
  • Configuration file (remove sensitive data)

Next Steps

Copyright © 2024 QMKonnect. Distributed under the MIT License.