Skip to main content
Terminal problems have distinct signatures. Reading the right one saves a lot of time.

​
Punches are not appearing

This is the common report, and it has four causes with completely different fixes. Work through them in this order.
1

Is the terminal user mapped?

By far the most likely. A punch whose terminal user ID does not resolve to an employee is parked — held, not lost.Check Attendance → Devices → Unclaimed users for IDs with no confirmed employee. Mapping one replays every punch waiting behind it automatically.
Also parks: an ambiguous suffix match, where two employee codes both end in the terminal’s number. OnTime refuses to guess.
2

Is the device registered?

An unregistered serial appears in the unclaimed list. Its punches are not attributed to your organization until you register it.
3

Is the device online?

A device silent for 5 minutes is marked Offline. If it is genuinely disconnected, the punches are in its flash, not lost — they arrive when it reconnects.
4

Is the connector reaching OnTime?

Check the connector’s logs for acknowledgement lines. No acknowledgements means it is not getting success responses from OnTime — see the next section.

​
The connector is not acknowledging

A wrong secret is silent from the device’s point of view. The terminal keeps retrying every 60 seconds and its queue backs up, but nothing surfaces in OnTime — because nothing reaches OnTime. Nothing is lost, but nothing arrives.If devices look healthy and OnTime looks empty, check the secret first.

​
A device shows Offline

Liveness comes from keepalive messages only. Silent for 5 minutes means Offline; the next keepalive flips it back.
An unstable network. Annoying, not harmful — punches sit in flash and deliver on reconnection.
Power or network at the device end, or the connector host is down. Check the connector first — if every device went offline at once, it is the connector, not the devices.
Unlikely, since delivery implies connectivity. Check whether the device is registered as a kiosk — kiosk-kind devices are exempt from the offline watchdog.

​
Punches land at the wrong time

Almost always DEVICE_TZ_OFFSET. F500 terminals report wall-clock time with no timezone, and the connector stamps every message with this configured offset. If it does not match what the terminals are set to, every punch is shifted.The damage is not cosmetic: shifted punches change late minutes, overtime bands, and which day a punch belongs to near midnight.
1

Check the terminal's own clock and timezone

In its admin menu.
2

Check DEVICE_TZ_OFFSET matches it

Default is +05:30.
3

If your sites span timezones, run one connector per zone

There is no per-device offset — the offset is connector-wide.
Punches already recorded at the wrong time need correcting as attendance — see Manual punches and overrides.

​
Punches landed on the wrong person

A mapping was wrong, or a suffix match resolved to someone unintended.
1

Fix the mapping first

So it stops happening.
2

Then correct the attendance

Deleting a mapping does not un-apply punches already applied. They are real events on real day records. Correct them with day overrides on both employees — the one who was wrongly credited and the one who was missed.
This is the argument for explicit mappings over the numeric-suffix convention. Suffix matching works until two codes collide, and by then it has already misattributed a day.

​
A punch appears twice

Deduplication is on (device, transaction ID, log time) together, and it is reliable. If somebody appears twice from one terminal, they punched twice.A punch from two different sources — a terminal punch and a mobile punch for the same arrival — is a different thing, and OnTime flags it as a conflict on the live board so you can decide which is real.

​
A device does not appear at all

Check the device’s LogServer IP and port, and that the connector’s port is reachable from the device’s subnet. A firewall between them is the usual cause.
Check the container. It should be running with a restart policy.
Visible in the connector’s logs. Unparseable bytes are deliberately not acknowledged, so a device sending malformed data will retry indefinitely. Usually a firmware or model mismatch — the connector targets F500-class LogServer devices.

​
Verifying a fix

Do not wait for a real punch. Replay a session with the fake device — it exercises the whole path in seconds. See Test with a fake device.