2026-06-02

USB HID Feature Report Debugging: GET_REPORT, SET_REPORT, Vendor Commands, and Missing Device Settings

How to troubleshoot HID Feature Report failures, GET_REPORT, SET_REPORT, report IDs, control transfers, vendor settings, device configuration, and USB HID firmware bugs.

HID devices are not only keyboards and mice. They include security keys, sensors, control panels, vendor tools, industrial devices, game controllers, UPS devices, and custom configuration interfaces. Many of these devices use HID Feature Reports for configuration and status. When Feature Reports fail, users search for "HID Feature Report not working", "GET_REPORT failed", "SET_REPORT failed", "HID report ID mismatch", and "USB HID vendor command timeout" because normal input may work while configuration does not.

Bus Scope is useful because Feature Reports often travel over endpoint zero as control transfers. The actual setup packet, report type, report ID, length, and response status matter.

What Feature Reports are

HID has several report types:

Input reports
Output reports
Feature reports

Input reports often arrive on interrupt IN endpoints. Feature reports are commonly requested with control transfers using GET_REPORT or SET_REPORT.

If a device's buttons work but its settings panel fails, Feature Report handling may be the reason.

Report ID and length mismatches

Many HID devices use report IDs. If the host includes report ID 3 and firmware expects report ID 0, the request can fail or return wrong data.

Common bugs:

Firmware omits report ID byte.
Host sends wrong report length.
Descriptor declares one length, firmware returns another.
Feature report exists in firmware but not descriptor.
Descriptor declares report that firmware never implements.

The HID report descriptor and the control transfer must be compared.

GET_REPORT and SET_REPORT evidence

Look for:

Setup packet request type.
HID GET_REPORT or SET_REPORT.
Report type Feature.
Report ID.
wLength.
Data stage bytes.
STALL or timeout.

If the device stalls a Feature Report that its descriptor advertises, firmware or descriptor consistency is suspect.

Vendor configuration through HID

Many products use HID because it avoids custom kernel drivers. Vendor settings may be implemented as Feature Reports.

Examples:

Change sampling rate.
Read firmware version.
Set LED mode.
Configure sensor range.
Enable bootloader.
Read calibration data.

If these commands fail, the device may still appear as a valid HID device.

Debug checklist

Use this process:

Capture enumeration and HID descriptor.
Save the HID report descriptor.
Identify Feature Report definitions.
Capture the failing GET_REPORT or SET_REPORT.
Check report ID.
Check requested length.
Compare descriptor length with transfer length.
Look for STALL, timeout, or short response.
Compare working input reports with failing feature reports.
Preserve descriptor and control transfer together.

Final diagnosis

HID Feature Report failures are usually descriptor, report ID, length, firmware state, or control-transfer handling problems. Input can work while configuration fails.

Bus Scope helps expose the HID report contract and the exact control transfer that failed, making Feature Report bugs diagnosable instead of mysterious vendor-tool errors.

Read the control transfer as a Feature Report request

The short answer: confirm report type, report ID, interface recipient, requested length, and status before blaming the settings application. HID class requests commonly use endpoint zero, so a successful interrupt-IN input stream does not prove that Feature Reports are implemented correctly.

Field to capture	What it answers	Common failure signal
`bmRequestType`	Direction, class request, interface recipient	Request is addressed to the wrong interface or direction
`bRequest`	Whether this is GET_REPORT or SET_REPORT	Host/application uses the wrong operation
`wValue`	Report type in high byte and report ID in low byte	Input/Output used where Feature was expected; ID mismatch
`wIndex`	Interface number	Composite device receives the request on the wrong interface
`wLength`	Expected data-stage byte count	Descriptor, host buffer, and firmware disagree
Data/status stage	Payload and device response	STALL, timeout, short transfer, or stale returned bytes

Do not infer the report ID from a UI label. Read it from the descriptor and from the low byte of wValue. A device using report IDs may include an ID byte in some host APIs while the on-wire control transfer identifies the report separately; compare the actual transport contract, not assumptions from one library.

Compare descriptor declarations with firmware behaviour

The HID report descriptor is the public contract. It tells the host which report types, IDs, sizes, and fields are exposed. Firmware may maintain internal structures that look similar, but the externally declared bits and bytes are what the host can legally request.

Comparison	Evidence to preserve	Diagnosis if they differ
Feature item exists	Descriptor fragment and report ID	Firmware-only setting is not reachable through standard HID request
Bit/byte count	Report Size/Count and calculated report length	`wLength` or response buffer is wrong
Report ID	Descriptor Report ID and request `wValue`	Host/firmware select different report
Interface	HID interface number and `wIndex`	Composite routing is wrong
Returned data	Data-stage bytes and expected fields	Endianness, packing, or state bug

Calculate the length from the descriptor rather than copying a C struct size. Padding, bit fields, report IDs, and compiler alignment can make an internal struct length unsuitable as an on-wire HID report length.

Separate GET_REPORT from SET_REPORT failures

GET_REPORT is device-to-host after the setup stage; SET_REPORT sends host-to-device data. The same report ID can expose different faults in each direction. A GET may STALL because firmware has no current value or mishandles the control-read callback. A SET may acknowledge but silently ignore bytes because field packing or validation is wrong.

Symptom	Evidence path	Likely area to inspect
GET_REPORT STALLs immediately	Setup packet matches descriptor, device returns STALL	Firmware request dispatch or unsupported runtime state
GET_REPORT returns too few bytes	`wLength` exceeds data-stage length	Report-size calculation or premature control completion
SET_REPORT STALLs	Setup/data stages reach endpoint zero then fail	ID/type validation or write callback
SET_REPORT ACKs but setting unchanged	Data bytes are accepted; next GET shows old value	Field parsing, persistence, or command semantics
Configuration works once after reset	Capture first working and later failing transaction	State machine, authorization, or power-mode dependency

Repeat one request after a known-good reset and once after the failure state. The difference in request, response, and preceding traffic is usually more useful than a single isolated capture.

Capture a minimal reproducible HID Feature Report case

Record enumeration through the HID and report descriptors.
Save the exact application action that triggers one GET_REPORT or SET_REPORT.
Record the setup packet, data stage, status stage, and timestamp.
Repeat with a working report ID or known-good firmware if available.
Note interface number, active configuration, and any prior vendor command.
Export the descriptor and matching transfer window as one case artifact.

QA question	A conclusion supported by the capture
Does the descriptor advertise this Feature Report?	Yes/no with the defining descriptor item
Is the request type/ID/interface correct?	Exact setup-field comparison
Is the requested length correct?	Calculated descriptor length versus `wLength`
Did the device receive/send the expected bytes?	Data-stage evidence, not only UI state
Where does failure occur?	Setup validation, data transfer, status, or later firmware state

HID report descriptor debugging explains the descriptor side, USB control transfer stall debugging covers endpoint-zero status failures, and USB composite device driver binding is relevant when the request lands on the wrong interface.

Can normal HID input work while Feature Reports fail?

Yes. Interrupt-IN input reports and endpoint-zero Feature Report transactions use different paths and callbacks. Working buttons or sensor data prove only that the input path is functioning.

Is a STALL always a firmware bug?

No. It can indicate an invalid report ID, wrong interface, unsupported report type, length mismatch, or an application request that is not valid in the device's current state. The descriptor and setup packet determine which explanation is credible.

For an engineering handoff, attach the descriptor, the raw setup/data/status stages, the host API call that initiated them, firmware revision, and one working comparison. That bundle lets another team reproduce the contract mismatch without relying on a paraphrased error dialog.

If the descriptor and transfer agree but the device state still differs, stop inferring from USB alone and add firmware logs or a debugger trace at the request handler. The capture has then narrowed the problem to a semantic state or persistence path rather than an on-wire mismatch.

Continue with the Bus Scope USB diagnostics blog, inspect USB descriptor debugging, or download Bus Scope to retain the descriptor and transfer evidence together.

How do you accept a HID Feature Report fix?

Start from the report descriptor and identify Feature report ID, bit/byte length, usage context, and interface. Then preserve the complete endpoint-zero request: bmRequestType, bRequest, wValue report type/ID, wIndex interface, wLength, data bytes, and status stage. The host API call, descriptor, and on-wire request must describe the same contract.

Test	Evidence	Pass condition
GET known ID	Descriptor plus control-IN stages	Exact expected length and decoded value return
SET known ID	Control-OUT data/status	Device accepts and applies supported fields
Read-after-write	Second GET or authorized device evidence	Persistence policy is explicit and correct
Unknown ID	Reproducible rejection	Device stays responsive and EP0 recovers
Wrong length/interface	Bounded failure behavior	No silent buffer overrun or state corruption
Reconnect/reset	Fresh GET of documented defaults/persisted state	State follows the product contract

Do not infer Feature behavior from working Interrupt-IN reports; they use a different path. Compare a known-working host call with the failing one and change only report ID, interface, length, or state in each test. If the USB transaction is valid but the returned semantic value is wrong, pair the trace with firmware-handler logs rather than rewriting the descriptor to match a bug.

Acceptance includes repeated GET/SET cycles, one invalid request, a reconnect, and confirmation that unrelated input reports continue. Keep failed and corrected sequences in the Bus Scope sessions workflow and use the HID input-lag guide only when the problem belongs to Interrupt-IN report delivery rather than Feature control transfers.

Report ID zero and host API conventions

Check how the host API represents Report ID zero. Some calls include a leading ID byte in the application buffer even when the on-wire Feature payload has no nonzero ID; others expose length or buffer rules that differ by platform. Preserve the API arguments and the resulting setup/data bytes rather than comparing application buffers alone.

Calculate expected length from the descriptor’s Report Size and Report Count, including padding and any report-ID byte required by the host contract. Test exact length first, then one shorter and one longer invalid request under a controlled fixture. Firmware must not read beyond valid data, return stale bytes, or corrupt the next endpoint-zero request.

Verify persistence and ownership explicitly

A successful SET followed by GET on the same connection may only prove RAM state. Reconnect, USB reset, device reboot, and power cycle separately according to the documented persistence policy. Record which transition should preserve or reset each field. If a Feature value controls another interface or downstream component, retain the semantic device-side evidence needed to prove that effect; USB completion only proves the control transaction.

Compare Windows and Linux host paths when both are supported, keeping firmware, descriptor, report ID, and desired value fixed. Platform API differences are a useful boundary, but the final on-wire contract should remain explainable. Close the case with exact descriptor fields, setup packet, payload, status stage, readback, persistence result, invalid-request behavior, and the first successful unrelated input report.

Retain one default-value capture from a fresh device and one modified-value capture. That pair shows which bytes actually changed and prevents padding, reserved fields, or an unrelated report ID from being described as the accepted Feature value.

Practical questions

What is the fastest reliable way to start?

Use the smallest representative case, write down the expected result, and change one variable. Confirm the basic path before adding filters, effects, edits, automation, or a larger source. This creates a baseline that can be compared after every later decision.

Related guides

Continue with the same-language pages below. They cover adjacent stages without changing the canonical owner of this topic: