Troubleshooting

Troubleshooting

"No records fetched" even though employees swiped in

Most likely cause: BioStar employees don't have shift schedules assigned.

Fix: Log into the BioStar admin portal, navigate to Time & Attendance → Users, and verify each employee has a Schedule assigned. Run a manual report in BioStar UI for the same date range — if it shows no records there, the API won't either.

Authentication fails with 401 / "Login failed"

Possible causes:

1. Wrong username or password in Biometric Settings
2. BioStar account is locked (too many failed attempts)
3. The TA URL is incorrect (pointing to the main BioStar server instead of the TA module URL)

Fix: Verify credentials by logging into the BioStar web portal manually using the same username/password. Confirm the TA URL by checking the BioStar admin settings — the TA URL is often on a specific port (e.g. :3000 or :443).

"Employee not found" warnings in error log

Cause: The employee ID in BioStar does not match any employee in Frappe HR.

Fix: Ensure the employee's ID or code in Frappe HR matches the user ID in BioStar. The matching is based on identifier — check your Frappe HR employee records and compare with BioStar user IDs. You may need to update one side to align them.

Duplicate checkin records appearing

Cause: The same date range was synced twice, and duplicate detection did not catch it.

Investigation: Duplicate detection checks for the exact timestamp match. If duplicates are appearing, it may be that timestamps from BioStar differ slightly across pulls (e.g. milliseconds). Check the Employee Checkin records directly and inspect the time field.

Fix: Delete the duplicate records manually, then investigate whether the BioStar API is returning slightly different timestamps for the same event across calls.

Scheduled task is not running

Checklist:

1. Is is_active checked in Biometric Settings? → If not, the task exits immediately
2. Is the bench scheduler running? → bench scheduler status
3. Is the background worker running? → sudo supervisorctl status
4. Are there errors in Frappe Desk → Background Jobs → Scheduled Jobs?

Sync runs but Attendance records are not being created

Cause: Employee Checkin records exist, but Frappe HR's auto-attendance is not converting them to Attendance.

Fix: This is a Frappe HR configuration issue, not a biostar issue. Check:

1. Does the employee have a Shift Type assigned?
2. Is Enable Auto Attendance checked on the Shift Type?
3. Has the Frappe HR scheduler job "Mark Attendance" run? (check Scheduled Jobs)

Network/SSL errors reaching BioStar

Cause: The BioStar server uses a self-signed certificate and the Frappe server's Python environment does not trust it.

Fix options:

1. Install the BioStar server's CA certificate on the Frappe server's OS-level certificate store
2. If in a controlled environment, configure the Python requests session to disable SSL verification (not recommended for production)
3. Obtain a proper TLS certificate for the BioStar server (e.g. from Let's Encrypt or your internal CA)