Skip to content

Name the cause when libfprint cannot drive the fingerprint reader - #11047

Open
codeclawd wants to merge 3 commits into
omacom:quattrofrom
codeclawd:fingerprint-validity-hint
Open

codeclawd wants to merge 3 commits into
omacom:quattrofrom
codeclawd:fingerprint-validity-hint

Conversation

@codeclawd

Copy link
Copy Markdown

omarchy-hw-fingerprint matches readers on vendor ID, and 06cb and 138a are both on its list. Three of those devices — 06cb:009a, 138a:0090 and 138a:0097 — have no libfprint driver at all; only the community's reverse-engineered python-validity daemon talks to them.

So omarchy setup security fingerprint detects a reader, installs libfprint-git, and runs all the way to enrollment before fprintd reports No devices available. That surfaces as:

Enrollment failed. Please try again.

which is indistinguishable from a bad swipe, and sends people into a retry loop that cannot succeed. The script already anticipates this shape of failure — the comment above setup_pam_config notes that an Elan MOC sensor outside the elanmoc table "gets this far and then fails to enroll" — this just names the cause for the three devices where it's knowable up front.

Change

On enrollment failure, check for those three IDs and say what's actually wrong:

Enrollment failed: libfprint has no driver for this reader.
It is a Synaptics/Validity sensor that only the community
python-validity driver can talk to, so retrying will not help:
  https://github.com/uunicorn/python-validity

Only the failure message changes. Nothing new is installed, the supported path is untouched, and the device list is python-validity's own udev match set from 94-validity-sensors.rules rather than a guess.

Verification

Tested on a ThinkPad T480 with 06cb:009a (Synaptics Metallica MIS Touch), where the reader does work once python-validity is driving it — fprintd-list goes from "No devices available" to "found 1 devices", and enrollment and fprintd-verify then succeed.

The helper honours OMARCHY_USB_DEVICES_PATH, so it is testable the same way omarchy-hw-fingerprint is:

  • real sysfs on that machine → matches
  • device tree containing only an unrelated 1234:5678 → declines
  • empty device tree → declines

🤖 Generated with Claude Code

https://claude.ai/code/session_01CqYR76DqmNVGYtGYUpyJmv

omarchy-hw-fingerprint matches readers on vendor ID, and 06cb and 138a are
both on its list. Three of those devices -- 06cb:009a, 138a:0090 and
138a:0097 -- have no libfprint driver at all; only the community's
reverse-engineered python-validity daemon talks to them.

So setup detects a reader, installs libfprint-git, and runs all the way to
enrollment before fprintd reports "No devices available". That surfaces as
the generic "Enrollment failed. Please try again.", which is
indistinguishable from a bad swipe and sends people into a retry loop that
cannot succeed.

Check for those three IDs on enrollment failure and say what is actually
wrong, pointing at python-validity. The device list is python-validity's own
udev match set from 94-validity-sensors.rules.

This only changes the failure message; nothing new is installed and the
supported path is untouched.

Verified on a ThinkPad T480 with 06cb:009a (Synaptics Metallica MIS Touch),
where the reader does work once python-validity is driving it. The helper
matches that device, and declines both an unrelated device and an empty
device tree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CqYR76DqmNVGYtGYUpyJmv
python-validity's SupportedDevices drives 138a:009d as well as the three IDs its udev rules match, and the pinned libfprint-git lists it under known unsupported devices, so it hit the same "Please try again" dead end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Codex Medium <noreply@openai.com>
@omarchybot omarchybot added the verified Omarchy Triage has verified that this issue is ready for final review label Oct 2, 2026
@greptile-apps

greptile-apps Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Medium risk] Improves error messaging when fingerprint reader lacks a driver.

The PR appears safe to merge; no outstanding finding or new actionable issue was identified.

Summary

The PR adds a no-device check before giving driver-specific guidance after enrollment fails, and adds USB fixtures for that guidance and the retry fallback.

Reviews (2) · Last reviewed commit: "Name a driverless reader only when fprin..."

Comment thread bin/omarchy-setup-security-fingerprint Resolved
Comment thread bin/omarchy-setup-security-fingerprint Resolved
@omarchybot omarchybot added the ready Good to merge label Oct 2, 2026
Keyed on the USB ID alone, the message also fired when a reader python-validity already drives failed for a bad swipe or a timeout, telling the user a retry could not help when it could. fprintd-list reporting no device is what says libfprint could not claim it. The setup test now covers the listed reader with and without a device, and an unlisted one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed and verified at 712eb38, with two small commits pushed to your branch. I reviewed it with Codex Medium as a second opinion, which can see my reasoning, so where it agreed that is not independent confirmation.

The problem is real. On a worker with the pinned libfprint-git (1:1.94.100.r10.g6f9479c-1), its hwdb lists 06cb:009a, 138a:0090, 138a:0097 and 138a:009d all under "Known unsupported devices". With real fprintd and a fake sysfs tree holding each ID, quattro ends in "Enrollment failed. Please try again." for all four. This branch names the missing driver for all four, keeps the generic message for an unlisted Validity reader (138a:003d), and reverting the change brings the old message back.

What I pushed:

  • 212b752 adds 138a:009d. python-validity's SupportedDevices in validitysensor/usb.py drives it as well as the three IDs its udev rules match, and libfprint has no driver for it either, so it hit the same dead end. Codex flagged it too.
  • 712eb38 shows the no-driver message only when fprintd-list reports no device. Keyed on the USB ID alone, a reader that python-validity already drives would get "retrying will not help" after a bad swipe or a timeout, when a retry could work. Codex and Greptile both raised this. The commit also adds three fixture-backed cases to test/shell.d/fingerprint-package-test.sh that check the message, not just the exit: a listed reader fprintd cannot see, the same reader when fprintd can see it, and an unlisted reader.

Tests: ./test/cli and the fingerprint-package (8 cases), hw-fingerprint, fingerprint-invitation and privileged-heredoc shell tests pass on the worker at 712eb38, and CI is green. No real Validity reader was available, so enrollment itself was not exercised.

Second opinion: Codex's last round on 712eb38 found nothing open in the script. It pointed out that the older cases in the setup test still read the host's /sys. I left that alone because none of those cases checks the message.

Related: #13187 takes the other route for the same readers and installs python-validity from the AUR, which is a decision for the maintainer. If it lands, this message needs to know which backend setup chose. #11721 and #13754 report this failure on 06cb:009a. This PR makes the message accurate but does not make setup work or stop it before enrollment, so it isn't linked to close them. #11841 and #10892 report the same dead end on other readers libfprint cannot drive (27c6:55b4, 138a:003d), which this list doesn't cover.

This is now waiting on the maintainer.

@jandrusk

Copy link
Copy Markdown

Looks good — clear message + tests for the Validity/python-validity readers that libfprint cannot drive (#13754).

Please coordinate with #15185 (skip those IDs at detect) and #15080 (name fprintd-invisible readers) so we don't ship three partial answers. Happy to take the messaging half from this PR if detect-side lands in #15185.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working compatibility Make Omarchy work better on everything! ready Good to merge verified Omarchy Triage has verified that this issue is ready for final review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants