Skip to content

Troubleshooting

dilshan edited this page Nov 22, 2026 · 1 revision

Troubleshooting

olru_probe returns 0 (no sensor found)

  1. Check the sensor is visible: lsusb. Note its id.
  2. Is the id supported? See Supported Devices.
  3. If it is 2009:7638 / 2109:7638, make sure OLRU_DENY_MSC is not set in your environment: env | grep OLRU.
  4. Re-plug the sensor and probe again (bus/address numbers change).

OLRU_ERR_ACCESS - permission denied

Your user cannot open /dev/bus/usb/<bus>/<address>.

  • Install the udev rule and re-plug:
    sudo cp udev/99-openlru.rules /etc/udev/rules.d/
    sudo udevadm control --reload-rules && sudo udevadm trigger
  • Quick test only: run the program with sudo.
  • Check the node: ls -l /dev/bus/usb/001/003.

OLRU_ERR_NO_DEVICE

The sensor was unplugged, or its address changed after a reset. Close the handle, call olru_probe again and re-open.

olru_open fails with OLRU_ERR_IO, OLRU_ERR_TIMEOUT or OLRU_ERR_PROTOCOL

  • The sensor did not answer the handshake. Re-plug it and try again.
  • Try a different USB port or cable; avoid unpowered hubs.
  • Make sure no other program (for example the vendor demo) has the sensor open.
  • OLRU_ERR_PROTOCOL can mean the device is not a sensor of a supported type (an ordinary storage product sharing the same id).

olru_capture_image keeps returning OLRU_ERR_NO_FINGER

That is the normal answer for an empty sensor. If a finger is on it:

  • press firmly and cover the glass window completely;
  • clean the sensor glass and the finger (very dry or wet fingers read poorly);
  • wait a moment after plugging in.

olru_read_template returns OLRU_ERR_DEVICE

The sensor could not extract features. Read the reason:

printf("%s\n", olru_device_code_text(olru_device_code(dev)));

Typically image too messy, too few feature points or finger too dry/wet. Capture again with a better placed finger. Remember to capture first - olru_read_template needs a fresh image in the sensor.

The image looks upside down

The library returns rows in the same order as the vendor SDK and writes the BMP the same way, so BMP viewers show it as the SDK does. If you draw the raw buffer top-down yourself, flip the rows vertically (see the PGM recipe in Examples).

The kernel driver is gone after using the sensor

olru_open detaches usb-storage from MSC-type sensors and olru_close does not re-attach it. Unplug and re-plug the sensor. This has no effect on the library, which does not need that driver.

A USB storage stick disappeared / was disturbed

You probably opened a storage product that shares the sensor's USB id. Unmount and re-plug it, and set OLRU_DENY_MSC=1 or select the device by bus/address in future.

Build problems

Message Fix
linux/usbdevice_fs.h: No such file sudo apt install linux-libc-dev
gtk/gtk.h: No such file sudo apt install libgtk-3-dev pkg-config (only needed for examples; make lib works without)
undefined reference to olru_... add build/libopenlru.a (or -lopenlru) after your source file on the compile line

Still stuck?

Collect: the output of lsusb, the olru_strerror text of the failing call, olru_device_code() if the error was OLRU_ERR_DEVICE, and your kernel version, then open an issue.

Clone this wiki locally