8.0 Troubleshooting

Troubleshooting

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.

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.

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.

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.

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).