Troubleshooting

Troubleshooting

Everything a run does is written to the Nexus Attendance Log. Start there.

Lines are prefixed by how much they matter: [PROBLEM] stopped something, [WARNING] is worth a look, [REFUSED] is one punch HRMS would not accept.

Messages, and what to do

What the log says	What it means
Nothing was read: nobody active has an Attendance Device ID yet	No Employee has that field filled in, or none of them are Active. See Setting up your devices, step 2.
… held 214 punches: 10 from active staff, 204 from people with no matching active Employee	The machine holds punches from user IDs that do not match any Active employee. Usually old staff, or an Attendance Device ID that was never filled in.
front-door was left alone: it is read every 60 minutes and only 12 have passed	The scheduled run came too early. Use Sync Attendance Now, which ignores the wait, or clear that device's Last Read.
[PROBLEM] Could not reach front-door at 192.168.1.201:4370	The machine did not answer. See below.
[WARNING] front-door: the Device Password is not a number	That field holds letters. Clear it, or put the machine's numeric communication key in it.
[WARNING] The Shift Type Device Mapping is not valid JSON	The mapping box has a typo. The sync carried on; only the Shift Type timestamps were skipped.
[WARNING] The mapping names a Shift Type that does not exist: Day Shift	Spelling. It has to match the Shift Type's name exactly.
[REFUSED] 101 at 2026-09-09 09:02: Transactions cannot be created for an Inactive Employee	HRMS would not take that punch. That employee is not Active.

The machine will not answer

[PROBLEM] Could not reach … means the connection failed, not that the app is broken. In order of likelihood:

1. Wrong address or port. Ping the device from the server. Then check the port is really open: nc -vz 192.168.1.201 4370.
2. The server cannot reach that network at all. A cloud server cannot see 192.168.x.x in your office. See Networking.
3. Something else is holding the connection. ZK machines allow one SDK client at a time. Close BioTime or any other tool that talks to it.
4. A communication key is set on the machine but not in the Device Password field, or the other way round.

Nothing happens when I press Sync Attendance Now

The button runs the sync directly and waits for it, so if truly nothing happens the request never got there. Check the browser console, and check that your bench is running.

The hourly sync never runs

Three things have to be true:

bench --site your-site scheduler enable          # 1. scheduler on for the site

2. pause_scheduler must not be 1 in sites/common_site_config.json.
3. Background workers must be running — bench start in development, supervisor in production. The sync runs on the long queue.

Check Scheduled Job Log for scheduled_collection.

The progress bar is stuck

If a worker is killed mid-run, the status would otherwise say "running" for ever. After three minutes with no progress the app declares it failed by itself, and the next sync can start normally.

Directions are wrong

See How IN and OUT are decided. The two usual causes are a Shift Type not set to Alternating entries as IN and OUT, and a night shift longer than the fourteen hour limit.

If you have more than one door, this is worth reading: More than one door.

Still stuck

Open an issue with the relevant lines from the Nexus Attendance Log, your Frappe and HRMS versions, and your device model. Please remove any real names or addresses first.