---
title: "8.0 Troubleshooting"
space: "ZKTeco Biometric Integration for FrappeHR"
url: "https://docs.navari.co.ke/zkteco/63-troubleshooting"
updated: "2026-05-24"
---

## Troubleshooting

### Connection Failed

**Symptoms:** Error log shows a connection timeout or `ConnectionRefusedError` pointing to the device URL.



**Checks:**

- Ping the device IP from the Frappe server: `ping 192.168.1.100`
- Verify the port is reachable: `curl -v http://192.168.1.100/iclock/api/transactions/`
- Confirm no firewall rule on the server or network is blocking outbound HTTP to the device subnet.
- Ensure the device is powered on and has not changed IP address. If the IP changed, update the URL field in `ZKTeco Biometric Settings`.

### Authentication Error (401 / Token Failure)

**Symptoms:** Error log shows `401 Unauthorized` or `JWT token generation failed`.

**Checks:**

- Re-save the `ZKTeco Biometric Settings` document to force a fresh token request.
- Log into the ZKTeco device web interface directly using the same credentials to confirm they are valid.
- Check whether the device admin password was changed after initial configuration.
- Some devices have an account lockout policy after repeated failed logins — wait and retry, or reset the lockout from the device web interface.

### No Data Syncing (No New Check-in Records Being Created)

**Symptoms:** Scheduled jobs are running (visible in Scheduled Job Log) but no Employee Check-in records appear.



**Checks:** 

- Confirm **Enable** is checked on the settings document.
- Verify the `last_sync_timestamp` field is not set too far in the future (which would cause the date filter to return no results). Clear it to force a full fetch.
- Check the device's own transaction log to confirm punch events are being recorded on the device side.
- Verify the **Fetch Frequency** is appropriate — if set to Weekly, the job will only run once a week.
- Check Scheduled Job Log for the specific ZKTeco job to confirm it is running on schedule and not erroring out before reaching the fetch step.

### Employee Not Found

**Symptoms:** Error Log entries with the message `Employee not found for biometric ID: {code}`.



**Checks:**

- Go to the Employee master and confirm the **Biometric ID** field is populated with a value that exactly matches the `emp_code` in the device log.
- Check for data entry errors: leading zeros (e.g., `001` vs `1`), spaces, or case differences.
- If the employee was recently added, confirm their record is saved and the Biometric ID is correctly filled before expecting their punches to sync.

### User Enable/Disable Not Working

**Symptoms:** Employees can still badge in after checking out, or cannot badge in after checking in.



**Checks:**

- Confirm the employee record has a `userId` value linked to their ZKTeco device user account.
- Verify the device firmware version supports the user management API endpoints (`GET/PATCH /iclock/api/users/{id}/`). Older firmware may not expose these endpoints.
- Check Error Log for `ZKTeco User Status` entries — the API response code and body will be logged there.
- Confirm the integration's admin credentials have permission to modify user status on the device (some device configurations restrict this to a specific admin role).