Troubleshooting

Use the symptom below to find the likely cause and the shortest verified fix. Collect diagnostics only after you have checked the relevant connection, permission, or configuration step.

Device connection and service

A device does not appear

Cause: Logi Options+ or another HID++ manager can hold exclusive access to a receiver or device.

Fix:

1. Quit Logi Options+ first, including its background agent.
2. On Linux, also quit Solaar and other Logitech managers.
3. Open Settings > Permissions and check the device-access status.
4. If you installed udev rules while the device was connected, reconnect the receiver or power-cycle the wireless device.

Can't reach the background service

Cause: The GUI cannot reach the agent that owns device I/O and input capture.

Fix:

1. Leave OpenLogi open while it retries the connection.

2. On Linux, check and start the user service:

   systemctl --user enable --now openlogi-agent.service

3. On macOS, check the Login Items fix below.

4. Reinstall OpenLogi if the problem continues.

Device scanning is unavailable

Cause: The background service could not scan for devices.

Fix:

1. Check the agent log in Need logs.
2. Check the applicable macOS or Linux permission steps on this page.
3. Reconnect the receiver or device after you correct an access problem.

macOS permissions

Buttons do not remap after granting Accessibility

Cause: The agent needs Accessibility to capture OS-visible mouse buttons and run their bindings.

Fix:

1. In macOS System Settings, open the Accessibility list.
2. Enable OpenLogi Agent, not the OpenLogi GUI.
3. If the entry already exists, remove it and add OpenLogi Agent again.

Input Monitoring is granted, but devices cannot open

Cause: Input Monitoring is required to read HID++ data, including Bluetooth-direct mice.

Fix:

1. Quit Logi Options+ and other device managers.
2. Confirm that OpenLogi Agent has Input Monitoring.
3. Log out of macOS and log in again if access remains unavailable.

Login item disabled in System Settings

Cause: A disabled login item prevents the background agent from running.

Fix:

1. Open macOS System Settings.
2. Open Login Items.
3. Turn on the OpenLogi login item.

Linux device access and Wayland

udev rules do not grant mouse-input access

Cause: OpenLogi needs read/write access to /dev/hidraw*. It needs write access to /dev/uinput and read access to the mouse /dev/input/event* node. Rules from another manager often cover only the first two nodes.

Fix:

1. Install OpenLogi's supplied udev rules. See Installation.

2. Reload the rules and trigger udev:

   sudo udevadm control --reload-rules
   sudo udevadm trigger

3. Unplug and reconnect the receiver or power-cycle the wireless device.

4. Check Settings > Permissions again.

A Flatpak install shows no devices

Cause: The Flatpak cannot install the required host udev rules itself.

Fix:

1. Install the bundled rules on the host:

   flatpak run --command=cat org.openlogi.OpenLogi \
     /app/share/openlogi/udev/70-openlogi.rules |
     sudo tee /etc/udev/rules.d/70-openlogi.rules >/dev/null
   
   sudo udevadm control --reload-rules
   sudo udevadm trigger

2. Restart the Flatpak:

   flatpak kill org.openlogi.OpenLogi

3. Launch OpenLogi again.

Mouse profiles follow the wrong app on Wayland

Cause: Wayland does not support pointer-targeted mouse profiles. OpenLogi follows the focused application instead.

Fix: Focus the application whose mouse profile you want before you use the binding. This limitation does not affect keyboard profiles, which always follow focus.

Changes and input capture

A device is offline and changes are pending

Cause: OpenLogi cannot apply a device setting while the device is offline.

Fix: Reconnect the device. OpenLogi applies the pending changes when it reconnects.

Buttons are not captured

Cause: The agent reads capture_mouse_events when it starts. Setting it to false disables the OS mouse hook. HID++ settings such as DPI and SmartShift continue to work.

Fix:

1. In config.toml, confirm this setting is enabled:

   [app_settings]
   capture_mouse_events = true

2. Restart the OpenLogi Agent.

3. On macOS, grant Accessibility to OpenLogi Agent.

4. On Linux, install the OpenLogi udev rules for the mouse event node.

Another app intercepts mouse input

Cause: Another macOS event tap can cause pointer lag or duplicate button actions.

Fix: In Settings > Diagnostics > Input interception, identify the listed app. Quit that app, then check the status again.

A device appears twice, or a receiver remembers old pairings

Cause: A receiver can retain pairings in slots that the device no longer uses.

Fix: Open the current device card's menu and select Remove old pairings…. This frees unused receiver slots without removing the device or its settings. Pair the device again if you later switch it to a removed channel.

Configuration file errors

OpenLogi opens a read-only error screen

Cause: The TOML schema rejects unknown, obsolete, malformed, and out-of-range values instead of silently changing them.

Fix:

1. Open the configuration folder from the error screen.
2. Correct the reported value in config.toml.
3. Relaunch OpenLogi after you save the file.
4. If needed, review config.toml.backup.1 through config.toml.backup.5 beside the configuration file. Restore only a backup you have reviewed.

The GUI refuses to save after an external edit

Cause: OpenLogi refuses its next save when an editor changes the file after the GUI loaded it. This prevents the GUI from overwriting the external revision.

Fix: Keep the external edit, then relaunch OpenLogi to load that revision. Do not retry the rejected GUI save.

Update requires a relaunch

OpenLogi was updated

Cause: The open window still runs the previous version after an update.

Fix: Select Relaunch OpenLogi. A relaunch loads the updated GUI.

Logs and bug reports

Need logs

Set OPENLOGI_LOG=debug before starting the affected CLI, GUI, or agent process to enable verbose tracing. CLI logs go to stderr.

The agent writes daily rotated agent.<date>.log files. It keeps at most seven files.

Use these hardware diagnostics when they match the symptom:

openlogi diag --help
openlogi diag features
openlogi diag controls

openlogi diag features reports the HID++ features that the active device exposes. openlogi diag controls reports reprogrammable controls and capability flags.

Report a bug

Fix:

1. In Settings, open About and select Copy Diagnostics.
2. Run openlogi diag features for the affected device.
3. Redact device IDs and serials from copied diagnostics and command output.
4. File the report in the OpenLogi issue tracker.