# How to Report a Bug in OpenLogi: A Complete Guide to Effective Issue Reporting

> Learn how to report a bug in OpenLogi effectively. Follow our guide to use the GitHub issue template and provide all necessary details for a quick resolution.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-08-28

---

**To report a bug in OpenLogi, use the structured GitHub issue template at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) and include device details, version information, and a diagnostics dump generated via the GUI's "Copy Diagnostics" feature or CLI debug logging.**

OpenLogi relies on the **HID++ protocol** to communicate with Logitech hardware, making precise device and connection details essential for reproducible bug reports. The project provides a dedicated GitHub issue template that automates labeling and guides reporters through required fields. Following the official reporting workflow ensures maintainers can triage and diagnose issues efficiently.

## Using the Official Bug Report Template

The fastest way to submit a valid bug report is to start from the template at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) in the `AprilNEA/OpenLogi` repository. This YAML-formatted template automatically applies the `type: bug` label and a `needs: triage` tag, routing your issue to the correct workflow filled with structured fields rather than free-form text.

## Pre-Flight Checklist Before Reporting

Before creating a new issue, complete the checklist embedded in the template:

- **Search existing issues** to avoid duplicates.
- **Update to the latest release** (or test against a recent `master` build).
- **Quit Logitech Options+**—only one application may own a HID++ receiver at a time.

Missing any of these steps often results in bugs being marked "impossible to reproduce" according to the template's opening note.

## Required Information for HID++ Debugging

### Core Metadata Fields

The template requires specific fields that pinpoint hardware and software context:

- **Component**—specify whether the bug affects the GUI, CLI, or both.
- **OpenLogi version**—retrieve this from the GUI's *About* window or via `openlogi --version`.
- **Operating system** and **OS version/architecture** (macOS is the primary supported platform).
- **Device model**—e.g., "MX Master 3S + Logi Bolt receiver".
- **Connection type**—Logi Bolt, Bluetooth-direct, wired USB, or other.

### Selecting Affected Areas

Choose all relevant categories from the multi-select field, such as *Button remapping*, *DPI control*, *SmartShift*, or *Menu bar / tray*. This categorization routes the issue to maintainers with specific domain knowledge.

## Capturing Diagnostic Data

Providing a diagnostics dump gives maintainers a privacy-filtered snapshot of versions, capabilities, and internal state, dramatically speeding up diagnosis.

### GUI Method

1. Open the **About** window (menu → *OpenLogi* → **About**).
2. Click **Copy Diagnostics**.
3. Paste the clipboard contents into the "Diagnostics report" textarea of the issue form.

### CLI Method

Use the following commands to gather version, device list, and debug logs:

```bash

# Show the installed OpenLogi version

openlogi --version

# List connected devices and pairing state

openlogi list

# Run a command with verbose logging for the "Logs" field

OPENLOGI_LOG=debug openlogi list

```

Include the output of `openlogi list` to show receiver/device IDs and pairing state, as referenced in [`docs/USAGE.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md).

## macOS Permission Verification

If you are on macOS, verify system permissions before submitting. The template includes a *macOS permissions* section where you must confirm that **Accessibility** and **Input Monitoring** checkboxes are correctly set for OpenLogi. Missing permissions are a common source of "bugs" that are actually configuration issues.

## Structuring the Bug Description

After filling in the metadata fields:

1. **Describe the problem**—write a clear, concise narrative of what happened versus what you expected.
2. **Supply reproducible steps**—enumerate the exact actions that trigger the bug, numbered sequentially.
3. **Attach logs**—paste the output from `OPENLOGI_LOG=debug openlogi <command>` or the GUI diagnostics into the *Logs* field.

Once all required fields are populated, click **Submit new issue**. The maintainers will triage it automatically, and you’ll receive a reference number for future discussion.

## Summary

- **Use the template**: Start every bug report from [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) to ensure proper labeling and structure.
- **Include device specifics**: HID++ protocol debugging requires exact device models, connection types, and OpenLogi versions.
- **Attach diagnostics**: Use **About** → **Copy Diagnostics** in the GUI or run `OPENLOGI_LOG=debug openlogi list` in the CLI to capture state snapshots.
- **Check permissions**: On macOS, confirm Accessibility and Input Monitoring rights before reporting.
- **Verify uniqueness**: Search existing issues and test against the latest `master` build to avoid duplicates.

## Frequently Asked Questions

### Where is the bug report template located in the OpenLogi repository?

The bug report template is located at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) in the AprilNEA/OpenLogi repository. This file defines the structured form that appears when you select "Bug report" from the GitHub issue creation menu, automatically applying the `type: bug` and `needs: triage` labels.

### Why does OpenLogi require device connection type in bug reports?

OpenLogi communicates with Logitech hardware using the **HID++ protocol**, and behavior varies significantly between connection methods like Logi Bolt, Bluetooth-direct, and wired USB. The connection type determines how the software initializes the device handle and parses feature reports, so omitting this detail often makes bugs impossible to reproduce.

### How do I generate debug logs from the OpenLogi CLI?

Set the environment variable `OPENLOGI_LOG=debug` before running any command. For example, execute `OPENLOGI_LOG=debug openlogi list` to capture verbose output showing protocol handshakes and device enumeration. Paste this output into the *Logs* field of the issue template.

### What should I do if I also use Logitech Options+?

Quit Logitech Options+ completely before testing or reporting bugs. Only one application may own the HID++ receiver at a time; running both simultaneously causes device access conflicts that appear as OpenLogi bugs but are actually resource contention issues.