ZKTeco BioTime Device Offline? How to Fix ADMS Connection and Employee Sync Errors

ZKTeco terminals do not wait to be asked. They push: at each heartbeat the terminal calls your BioTime server over HTTP, delivers its punches, asks whether anything is waiting for it, and collects any employee changes in its queue. ZKTeco calls this ADMS. That one fact explains many "device offline" calls. A terminal shows as offline when it cannot reach the server, or reaches it and is ignored. The server never reaches into the terminal to find out why.

This guide is for administrators running ZKBio Time on their own server or on BioTime Cloud. It covers the connection first, then employee sync in both directions, then how to read the logs so you know which layer is failing. Menu names come from ZKTeco's ZKBioTime 8 manual and FAQ. Version 9 and the cloud edition use the same ideas with slightly different menus.

Symptoms: what you are seeing

These are the exact strings ZKTeco's own FAQ uses, so you can match them against your screen:

Command Log return value:   invalid -1100
Command Log return value:   Device Not Support ,Error:-1002
Terminal registration:      DeviceType=att   AccessRuleType=0
BioTime login page:         This site can't be reached, 127.0.0.1 refused to connect

Cloud or on-premise: what changes when you troubleshoot

With ADMS the terminal makes the call in both cases. Nothing has to reach into the terminal, so you do not need to open ports to it.

Step 1: Fix the terminal network settings

1. Go to Menu → Comm. → Ethernet on the terminal. The IP address, subnet mask, gateway and DNS must be valid for the network it is on. For a server on the same LAN, ZKTeco's guide says the terminal and the server must be in the same network segment.
2. Ping the terminal from a PC on the same network. No reply means look at the cable, the switch port or PoE, an IP conflict or a VLAN before touching BioTime.
3. If the terminal and the server are on different networks or at different sites, check that the route and any firewall between them allow the connection. For branches, use a VPN or use BioTime Cloud, which needs only internet access. See multi-branch attendance.
4. Give both the terminal and the server a fixed address, or a DHCP reservation. A server whose address changes overnight leaves every terminal calling the old one.

Step 2: Check the Cloud Server Setting on the terminal

Go to Menu → Comm. → Cloud Server Setting. On some models it sits under System settings → Cloud Service settings.

• Server Address: the IP address of the machine running BioTime. On the server, ipconfig shows it as IPv4.
• Server Port: the communication (ADMS) port, which is the port BioTime itself listens on: the number you type after the address in your browser, or the one in the BioTime service console. It is not 4370. That is the older PULL port used by desktop software.
• Enable Domain Name: off when you enter an IP address. On when you enter a domain name, as you do for a cloud service. Use the exact address and port your cloud account or supplier gives you.
• HTTPS: leave it off unless you have set up BioTime for HTTPS with a valid certificate. A mismatch between the terminal and the server here stops the connection.
• Proxy: off, unless your network forces one.

Then test from the terminal's side of the network. On the server, check which program owns the port. From any PC on the terminal's network, check that the port answers (8081 is only an example, so use yours):

netstat -ano | findstr :8081
Test-NetConnection 192.168.1.20 -Port 8081

You can also open http://192.168.1.20:8081 in a browser on that PC. If the BioTime login page loads, the path is open. If it does not, the fault is the route, the firewall or the service, not the terminal.

Port clashes. ZKTeco's FAQ describes the browser showing the Windows IIS page instead of BioTime on a 9.0.1 install, which means another web server holds the port. The fix is to change BioTime's port in the Biotime Platform Service Console, then update the port on every terminal.

If the login page says 127.0.0.1 refused to connect, check that the services are running and that the database test and table creation succeed in the console. Then confirm the console's HTTP port is the port you browse to. If it is, stop the service, click Check Port, and if the console says the port is invalid, change it and restart the service.

Step 3: Check the server: services, firewall, licence and clock

• Services. BioTime runs several Windows services whose names start with bio. All of them must be running. In Task Manager, check the services list. ZKTeco's FAQ says to start any that are stopped and deal with the error each one gives.

• Antivirus. The bio-server service depends on iclockservice.exe. If antivirus has quarantined it, the service will not start and BioTime cannot accept terminals. Restore or allow the file, then start the service.

• Firewall. Allow the BioTime port inbound. ZKTeco's FAQ suggests switching the firewall off to test. On a production server, add a rule for the port instead, and never leave the firewall off. In an administrator PowerShell (use your port):

  New-NetFirewallRule -DisplayName "BioTime ADMS" -Direction Inbound -Protocol TCP -LocalPort 8081 -Action Allow
  

• The server's clock. ZKTeco's FAQ records that BioTime 8.0 can suddenly stop opening after the server's time zone is changed, because it no longer matches BioTime. Set the time zone back and restart the service.

• Licence. ZKTeco's FAQ describes a case on ZKBio Time 8.0.6 where every device went offline after activation and new devices could not be added. Its answer is to have the licence checked for the PushKey option, which should not be selected. If your problem started with an activation, ask your supplier to check.

• A moved or renumbered server. Every terminal must be updated with the new address. This is the reason a working system goes offline after a server replacement.

Step 4: Make the terminal register: device type, auto add and area

Even when requests reach BioTime, it will only accept the terminal if it is an attendance-push device, and only communicate with it once it has an area.

• Device type. ZKTeco's FAQ is specific: BioTime supports attendance-push devices only, and you can check the values the terminal sends: DeviceType=att and AccessRuleType=0. Many ZKTeco terminals can run either access control (AC push) or attendance (TA push). Hybrid models should be set to attendance under Menu → System → Device Type (the path varies by model). A terminal set as an access control device never appears.
• Firmware variant. Some models are sold in variants, and one without ADMS cannot connect. If a terminal that meets every other check still will not, confirm the model and firmware variant with your supplier.
• Auto add. ZKTeco recommends letting BioTime add the device itself when it detects the terminal's request, rather than adding it by hand. Allow Auto Add is under Device → Configuration.
• Give it an area. An auto-added device is listed under the name Auto add, and per ZKTeco's manual it must be assigned a custom area, not the default one, before it will communicate. Find the entry by the serial number on the terminal, open it, and set its name, its area and its time zone. Use New Area if the area does not exist yet.

BioTime's device list then shows the device's Firmware/Push Version, Last Activity, User Qty, FP Qty, Face Qty, Transaction Qty, Last Sync and Cmd. Those columns are the quickest health check you have.

Step 5: Fix employees that will not sync to the terminal

BioTime turns each change into a command. The terminal collects it at its next poll, runs it and reports the result. So there are four places to look.

1. Area. The employee's area must include the terminal's area. Employees are synchronised to the devices in their area.
2. Sync mode. Under Device → Configuration, Data Sync Mode can be Real-Time, Timing or Manual. In Manual or Timing, nothing is sent until you sync or the set time arrives.
3. The Cmd column. It counts commands not yet executed. Click the number to see them. A number that never falls means the terminal is not polling (Steps 1 to 3) or is refusing the commands.
4. The Command Log. It shows what the terminal did with each command. ZKTeco's FAQ ties invalid -1100 to two cases: employees that will not upload from the terminal (the Registration Device setting, Step 6) and a user photo larger than about 25 KB that will not reach a terminal that shows photos. Reduce the photo and sync again. Device Not Support ,Error:-1002 means the terminal does not support that command, which points at a model or firmware variant.

Then use the tools BioTime gives you, from gentlest to heaviest:

• Re-synchronize to Device: in Personnel → Employee, select the employees and choose More → Re-synchronize to Device.
• Read Information: Device Menu → Read Information reads the person count, record count and firmware version from the terminal. ZKTeco's FAQ uses it when the face count in BioTime differs from the terminal's.
• Clear Pending Command: Device Menu → Clear Pending Command clears a stuck queue. It also discards changes waiting in it, so re-sync the affected employees afterwards.
• Sync Data to Device: under Data Transfer. This deletes the terminal's existing data (except event records) and downloads it again. Do it out of hours, with a steady network and power.

Three limits catch people out:

• ID length. BioTime allows an Employee ID of up to 20 digits, and a terminal may allow fewer. ZKTeco lists up to 14-digit user IDs on the SpeedFace-V5L, for example. Check your model.
• PIN length. BioTime's manual says black-and-white terminals support a PIN of at most 5 digits and colour-screen terminals 8. A longer PIN is cut off, so it no longer matches what the employee types.
• Employment type. A temporary or probation employee with a valid period is deleted from the devices when the period ends. That explains employees vanishing on a set date.

If you move employees between areas, ZKTeco's FAQ says to open the relevant registration device, sync manually and, if that fails, delete the cached device commands.

Step 6: Fix employees enrolled on the terminal that never reach BioTime

• Upload User Data. Device → Device → Data Transfer → Upload User Data pulls all or selected users from the terminal into BioTime. If it times out, run it again.
• Registration Device. Under Device → Configuration, the Registration Device option decides which devices may upload. If it is enabled, ZKTeco's FAQ says a device uploads its users only if Registration Device is Yes in that device's own record. Per the same FAQ, a device that is a registration device also has its users distributed to other devices in the same area, and one that is not uploads to BioTime but is not distributed to the others. When employees will not upload, invalid -1100 in the Command Log is the sign to check this setting.
• Allow Upload Name and Allow Upload Card. If names or card numbers are missing after an upload, check that these two options are on.
• Unique IDs. BioTime identifies an employee by ID. Two people enrolled with the same ID on different terminals cannot be told apart, and their punches and templates get mixed. Create employees in BioTime first and keep ID ranges per site.
• Remote fingerprint enrollment. Device Menu → Enroll Remotely starts fingerprint enrollment on a terminal for a given Employee ID, so the employee can enroll without an administrator at the device. It supports fingerprints only.

Step 7: Fix missing punches and wrong times

• Transfer mode. A device can transfer in real time or at set times. On a schedule, punches appear only at those times. The device's Heartbeat Request sets how often it calls in.
• Pull missing punches. Data Transfer → Upload Transaction brings in all transactions or a date range. A terminal that has been offline holds its punches until it can send them. For a terminal that never connects, ZKTeco's FAQ describes importing its records from a USB drive, and the device must exist in BioTime first.
• Time zone on the device. When you select a time zone in the device's BioTime record, the terminal's clock is synchronised to that time zone. Choose UAE time (GMT+4).
• Time zone on the server. The server's own time zone must be right and stay right (Step 3).
• Time zone in the database. ZKTeco's FAQ notes that on BioTime 8.0, PostgreSQL defaults to East 8, so the record table is in UTC+8, four hours ahead of the UAE. The fix is in the postgresql.conf file in the pgSQLData folder of BioTime's installation directory: comment out the timezone = 'Asia/Hong_Kong' line, then restart the Bio-pgSQL service. ZKTeco also notes that a terminal's time can jump after connecting. If it returns to normal when disconnected from the server, look at the server's time zone.
• Punches exist but the report is empty. ZKTeco's FAQ gives five checks: that there are attendance records, that a schedule exists, that attendance has been calculated, that weekends are set and scheduled consistently, and that punches fall inside the allowed time limits.

If payroll depends on these punches, see WPS-compliant attendance for the UAE overtime and export rules the numbers feed.

Step 8: Read the logs to find which layer is failing

Everything above falls into one of three layers. Working out which one saves hours.

Layer 1: Network. Does anything arrive? Look at BioTime's server output, the web server log or a packet capture for requests from the terminal's IP. A healthy terminal produces this pattern at each heartbeat:

GET  /iclock/cdata?SN=<serial>&options=all&pushver=<version>   introduces itself
GET  /iclock/getrequest?SN=<serial>                            asks for waiting commands
POST /iclock/cdata?SN=<serial>&table=ATTLOG                    uploads punches
POST /iclock/devicecmd                                         reports command results

The parameters vary with firmware and push version, but the paths are those of ZKTeco's push protocol. No requests at all means the network layer: Steps 1 to 3.

Layer 2: Protocol. Requests arrive but are ignored. The terminal is talking, and BioTime is not accepting it. Check what it declares itself as. DeviceType=att is right for BioTime, and DeviceType=acc (an access control device) is not. Check that Allow Auto Add is on, that the device has a custom area and that the licence does not carry PushKey. Steps 3 and 4.

Layer 3: Software. The device is online but commands fail. The Cmd count and the Command Log tell you. A return value of 0 means the terminal ran the command. Negative or invalid values mean it refused it: -1100 (the Registration Device setting, or an oversized user photo) and -1002 (an unsupported command). Then apply Steps 5 to 7.

What to collect before you call anyone

1. A screenshot of the Device → Device row: State, Last Activity, Firmware/Push Version, quantities and Cmd.
2. A photo of the terminal's Cloud Server Setting screen.
3. The last ten lines of the Command Log for the device.
4. The BioTime version, and whether it is on-premise or cloud.
5. What changed: a new server, a new IP address, a firmware update, a licence activation or a firewall change.

Related guides: Hikvision iVMS-4200 employee enrollment, Suprema BioStar device connection and user sync, and access control door not unlocking. See the full ZKTeco range.