Skip to content

Troubleshooting

Jump to bottom
Rex Ackermann edited this page Dec 8, 2025 · 2 revisions

Troubleshooting & FAQ

Common Issues

1. Camera not detected

  • Symptom: face-auth camera-test fails or crashes.
  • Fix: Check your device path in config.yaml. The default is 0 or /dev/video0. If you have multiple cameras (or IR emitters), you might need /dev/video2.
  • Command: ls -l /dev/video* to see available devices.

2. "No module named face_recognition"

  • Symptom: Python import errors.
  • Fix: Ensure you are running commands inside the virtual environment (source venv/bin/activate) or using the face-auth wrapper script which handles this for you.

3. Face not recognized in different lighting

  • Fix: Face recognition is sensitive to lighting. Use face-auth add-sample to add 3-5 more samples in the challenging lighting condition.

4. "libopenblas.so.0: cannot open shared object file"

  • Symptom: NumPy/dlib import fails with missing library error.
  • Fix: Install BLAS libraries. The installer should do this automatically with sudo ./install.sh. Manual fix: 
    # Fedora/RHEL
sudo dnf install openblas blas lapack

# Ubuntu/Debian
sudo apt install libopenblas-dev libblas-dev liblapack-dev

# Arch
sudo pacman -S openblas

5. Systemd service fails

  • Fix: Check logs with journalctl --user -u face-auth-monitor -e. Ensure DISPLAY and XAUTHORITY environment variables are correctly set in the service file (installer handles this, but manual moves might break it).

FAQ

Q: Does this work with IR cameras (Windows Hello hardware)? A: It works with the video stream from them, but Linux Hello currently uses standard OpenCV/dlib libraries which are optimized for RGB. It does not yet leverage specific IR depth features for anti-spoofing in the same way Howdy does, but it will function if the camera outputs a video feed.

Q: Can I use this for root? A: Yes, if you use the PAM module with sudo. However, we recommend keeping a password for root operations for security.

Q: Where is my face data stored? A: ~/.local/share/face-auth/face_auth.db. It is an encrypted SQLite database.

Q: I'm locked out! A: If PAM fails, it falls back to password. If you somehow broke PAM entirely, boot into a live USB, chroot, and revert changes to /etc/pam.d/.

PAM Troubleshooting

Face auth not triggering during sudo

  1. Check if face-auth is installed: which face-auth
  2. Test manually: face-auth pam-authenticate $USER
  3. Check PAM config: grep face-auth /etc/pam.d/sudo

Removing PAM quickly (emergency)

sudo sed -i '/pam_exec.so.*face-auth/d' /etc/pam.d/sudo
sudo sed -i '/pam_exec.so.*face-auth/d' /etc/pam.d/gdm-password

Known Issues

  • High CPU usage during enrollment (dlib dependency).
  • Rotation invariance adds latency (checking 4 orientations).
  • Conflict with other apps using the camera (only one app can access /dev/video0 at a time).

Clone this wiki locally