What This Article Covers

Once Face Recognition Login is live in your iVendNext POS deployment, ongoing management falls into three areas: keeping user enrolments current, troubleshooting failures at both the admin and cashier level, and understanding what the system does and does not do at the boundaries of its design. This article covers all three.

---

Keeping Enrolments Current

When to Update a Face Mapping

A face mapping is the reference against which every future login attempt is compared. If the user's appearance changes significantly from the reference photo, the Euclidean distance between their live face encoding and the stored encoding will increase, and login may start failing even for the correct person.

The following changes in appearance are most likely to affect matching accuracy:

• Significant weight gain or loss that alters facial structure.

• Growing or removing a beard or significant facial hair.

• Wearing glasses in the enrollment photo but not in daily use, or vice versa.

• Changes following medical procedures affecting facial appearance.

Minor day-to-day variation in lighting, hairstyle, or expression is tolerated by the matching threshold. The threshold is set at a Euclidean distance of 0.5, which provides reasonable tolerance for natural variation without becoming permissive enough to accept different people.

If a user reports that Face ID login consistently fails despite trying under good lighting conditions and positioning correctly, re-enrolment is the correct first response.

How to Update a Face Mapping

Via photo upload: Open the existing User Face Maps record for the user in iVendNext Desk. Attach a new photograph to the User Face field and save. The system regenerates the encoding automatically from the new photo. The previous encoding is replaced.

Via live camera: Open the User record in iVendNext Desk, click Actions → Update Face Map, and complete the live liveness-and-capture sequence. The system saves the new encoding on completion.

Both methods replace the existing encoding. There is no option to store multiple encodings per user — only one reference is active at any time.

Revoking Face Login Access

To remove Face ID login access for a specific user without disabling the feature for everyone:

1. Go to iVendNext POS → User Face Maps.

2. Open the record for that user.

3. Delete the record.

After deletion, the user sees the "No Face ID registered for user {username}" error if they attempt face login. They must use their password. Other enrolled users are unaffected.

Deleting the User Face Maps record does not deactivate the user's account or affect password login. It removes only the biometric credential.

Disabling Face Login Organisation-Wide

To turn off Face ID for all users at once:

1. Go to System Settings in iVendNext Desk.

2. Untick Allow Login using Face Recognition.

3. Save.

The Login with Face ID button is removed from the /login page immediately. All existing User Face Maps records are preserved in the database. If the feature is re-enabled later, enrolled users will be able to use Face ID again without re-enrolment.

Troubleshooting: Admin-Side Issues

The "Login with Face ID" Button Does Not Appear on the Login Page

This is almost always one of three causes:

The System Settings flag is not enabled. Go to System Settings, confirm that Allow Login using Face Recognition is ticked, and save. Hard-refresh the login page after saving.

The frontend JavaScript bundle is not deployed. The face detection widget is a separately built JavaScript file. After a fresh installation or update, it must be built and deployed: run the face-detection build step and then bench build --app ivendnext_pos. Without this step, the feature toggle has no effect because the widget code is absent.

The page is cached. A hard-refresh (Ctrl+Shift+R or Cmd+Shift+R) forces the browser to reload the page without cached assets.

Image Info Is Empty After Saving a User Face Maps Record

When you save a User Face Maps record with a photo attached and the Image Info field remains empty, the face encoding was not generated. Check each of the following:

Photo quality. The most common cause is a photo where no face is clearly detectable — poor lighting, a face turned away, sunglasses, a face mask, multiple people in frame, or a very small face in a large image. Try a clearer, front-facing photo under good lighting.

Python dependencies not installed. The server-side encoding relies on opencv-python-headless, dlib, and numpy being installed in the bench Python environment. If any of these are missing, encoding will fail silently or with an import error. Install them in the bench environment before using this feature.

dlib model files not present. The two dlib model files — shape_predictor_68_face_landmarks.dat and dlib_face_recognition_resnet_model_v1.dat — must be present in ivendnext_pos/ivend_imports/models/. These are included in the repository and should be present after git pull, but verify they exist if enrolment fails unexpectedly.

Frappe Error Log. Go to Error Log in iVendNext Desk and search for "Face Encoding Error." Any encoding failure writes a full traceback there, which will identify the specific cause.

Face Login Fails with a Server Error for All Users

If every face login attempt fails at the server stage, the most likely cause is that the Python dependencies are not installed. The modules cv2, dlib, and numpy are imported at the module level in the server-side face login files. If they are not installed, imports fail when those modules are loaded, producing server errors for all face login attempts.

Install the required packages in the bench Python environment and restart the bench. Check the Frappe Error Log for "Face Login Error" entries — the traceback will confirm whether missing dependencies are the cause.

Troubleshooting: End User Login Issues

Camera Does Not Open or Shows a Black Screen

The browser requires explicit permission to access the camera. If the user previously denied camera access for this site, the browser will not re-prompt — the user must go to their browser's site permissions settings, find the iVendNext POS site, and manually change the camera permission to Allow.

A black screen after the widget opens may also indicate another application is using the camera. Video conferencing tools, other browser tabs with active camera sessions, or certain security software can lock the camera device. The user should close other applications and try again.

Progress Bar Does Not Fill or Fills Very Slowly

The liveness score requires both a blink and a subtle head movement. If only one of these is happening, the score will fill partially and then stop.

Blink score (up to 60 points): A natural blink — the EAR falling below 0.19 for between 2 and 14 frames and then reopening — is required. Very slow eye closures or prolonged closures are rejected. A fast, natural blink is all that is needed.

Movement score (up to 40 points): The nose-tip must move between 0.004 and 0.028 normalised units per frame. A subtle nod or slight side-to-side head movement produces the right signal. Large, sharp movements are rejected as too fast.

If the bar starts decreasing rather than filling, the score is decaying because the user has become inactive. The blink score decays at 10 points per second (after a 2-second pause), and the movement score decays at 5 points per second (after a 1-second pause). The user should continue blinking and moving naturally rather than holding still waiting for the bar to complete.

"Face Match Failed. Access Denied."

This message appears when the server compares the live face encoding to the stored enrolment encoding and the Euclidean distance exceeds 0.5. The user is physically present and has passed liveness, but the comparison concludes that the live face is sufficiently different from the reference.

Common causes and responses:

Lighting conditions differ significantly from the enrolment photo. The server-side dlib model is sensitive to lighting, particularly when the enrolment photo was taken in very different conditions. Ask the user to move to an area with more consistent, even lighting.

Appearance has changed since enrolment. If the user grew a beard, significantly changed weight, began or stopped wearing glasses, or has any other notable change since the reference photo was taken, re-enrolment is the correct solution.

The enrolment photo was low quality. If the original reference photo was taken in poor lighting, at an angle, or without the face fully visible, the stored encoding may be unreliable. Re-enrol with a better photo.

The enrolment photo has not been processed. Check the User Face Maps record and confirm that the Image Info field contains a JSON array. If it is empty, the encoding was never generated and the comparison cannot succeed. Re-enrol the user.

"No Face ID Registered for User {username}"

This message appears when the server cannot find a User Face Maps record for the entered username, or when the record exists but the Image Info field is empty — meaning no encoding was ever generated for that user. The user must be enrolled before they can use Face ID login. Refer to the Face Login Setup article for enrolment steps.

"No Face Detected — Center Your Face in Frame"

This status appears during the liveness detection phase when the MediaPipe model cannot locate a face in the camera feed. The most common causes are:

• The user's face is too far from the camera, too small in the frame, or partially outside the frame boundary.

• Lighting is too low — the camera cannot distinguish facial features.

• The user is wearing a face mask or other covering that obscures the face.

• The user is backlit, with a bright light source behind them washing out the facial features.

The user should move closer to the camera, ensure their face is centred, and find an area with good, even lighting facing them from the front.

Login Appears to Succeed but the Page Does Not Redirect

In rare cases, the server creates a session successfully but the browser redirect to /app does not execute. Check the browser console for JavaScript errors. Ensure the browser is not blocking redirects for the iVendNext POS domain. Try refreshing the login page and attempting face login again.

Understanding System Boundaries

Face Login Is an Additional Method, Not a Replacement

Face Recognition Login coexists with password login. At any point, a user can ignore the Login with Face ID button and enter their password in the standard field. This is by design. If face login fails for any reason — poor lighting, a camera malfunction, a changed appearance — the user has an immediate fallback without needing administrator intervention.

Only One Face Mapping Per User

The system supports one reference encoding per user. There is no mechanism to register multiple encodings for the same user (for example, one with glasses and one without). If a user's appearance varies significantly between contexts, the best approach is to enrol them in their most typical working appearance.

The Matching Threshold Is Fixed

The Euclidean distance threshold of 0.5 is hardcoded in the server-side implementation. It cannot be adjusted per user, per store, or per deployment from System Settings. Changing it requires a code modification. This means the same tolerance applies to all users equally.

Internet Access Is Required for the First Use

The MediaPipe WebAssembly bundle and face landmarker model are loaded from external CDNs the first time they are used in a browser session. If the terminal does not have internet access, the face detection widget will fail to load. Once loaded, the model is cached in the browser session and does not need to be fetched again until the cache is cleared. Environments without internet access would need the model files self-hosted, which is not supported in the current implementation.

The Feature Does Not Apply to Mobile Native Builds

Face Recognition Login is implemented for the browser-based iVendNext POS login page. It is not available on Capacitor-based mobile native builds of the application.