-
Notifications
You must be signed in to change notification settings - Fork 2k
Troubleshooting
mcuee edited this page Jan 9, 2026
·
9 revisions
4 people trying to test a "you just have to do (some vague description)" is more of time waster than "here's a patch that you can use to test". The less time we need to spend trying to replicate your problem and get comprehensive data about it, the faster you will get help.
- Make sure you subscribe to libusb-devel and mail the list rather than the developers
- Check out libusb Wiki, especially the FAQ page.
- Check out libusb documentation, for example, check out the API for return values
- Always tell us the OS and OS version you use and libusb version you use. You should use the latest release version or latest git.
- Always tell us the device you use, an if it's not obvious, give us a description of what you want to do with it. To try to replicate the issue, we may have to find a similar device
- Always tell us if you use a custom firmware
- Try with a different device, and
- Try to provide us with a patch for xusb that we can use to replicate the issue. Of course xusb does not suit all situations, but it should be generic enough for simple one. If you do not want to use xusb, you can use a simple program as well.
- Always provide us with a complete log. Don't cherry pick.
- Check the limitations from each backend
- Give us a precise description of the steps we can reproduce the problem
- Try to test on a different OS: helps us identify if it's core or backend
- At least sign with your first name so that we know how to address you. Besides yada, we may reply to multiple people at once and it's a PITA to address someone as starshine1234
- if it's an issue with descriptors, don't just assume that libusb is the problem: try with USBView (Windows) or lsusb (UNIX)
https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/usbview
USB Device Tree Viewer can be uased as an alternatiev to usbview.
https://www.uwe-sieber.de/usbtreeview_e.html
lsusb (usbutils) is a common utility under Linux.
https://github.com/gregkh/usbutils
- a log goes a long way! libusb_set_debug() or LIBUSB_DEBUG=4 can do wonders.
- a trace is even better. And yes, Windows (7) can also generate insightful traces
- we have a generic test utility that can produce a log and will perform basic device access. You shouldn't come to us with "I can't access my device" but with "I can't access my device, and here is the log from xusb" at the very least, tell us the VID:PID of your device, its purpose, and whether it uses a custom firmware that you developed or a commercial one
- A search with basic keywords describing your issue against the libusb-devel mailing-list can be very insightful
- Are you aware that OS backends have limitations, and that not all devices will perform the same way on all devices?
- Always try to test with the latest version from git if you encounter an issue