Troubleshooting

Find the last working step, then check the step immediately after it. Reproduce with a test person where possible and record the time, page, device identifier, and exact error. Inspect status and logs before repeating submissions or clearing data.

Problem	Start here
Website cannot be reached	Website does not open
Page loads but login fails	Heartbeat works but login fails
Terminal is missing from System Configuration	System node is not discovered
Rooms are empty or enrollment is incorrect	Enrollment cannot be completed
Central person exists but device does not recognize them	Person is not synchronized
Recognition works but the display does not change	No new display event
Unreturned list differs from the site situation	Unexpected unreturned results

Website does not open

1. Check the browser address, protocol, and port against the handover address.
2. Ask a maintainer to inspect the Web service and open the homepage from the host itself.
3. If host access works but office-computer access does not, check VM networking, port mappings, routing, and the firewall.
4. If the homepage works but business requests fail, inspect the central reverse proxy and logs next.

Recovery check: Open the management page from the computer used in practice, then log in and query business data.

Maintainer reference: read-only checks

Run in the handover directory. Examples use the default Web port.

docker compose ps
docker compose logs --tail 100 web server
curl -I http://127.0.0.1/
curl --fail http://127.0.0.1/api/heartbeat

If Compose requires variable interpolation, provide configuration through the existing deployment environment. Do not paste complete configuration, passwords, or tokens into public issue reports.

Heartbeat works but login fails

A heartbeat checks the central health endpoint; it does not validate the school, account, or complete business database.

1. Verify the school entry point and account, including whether the credentials belong to another environment.
2. Record the visible error and request time. Log in again if the session has expired.
3. Ask an administrator to check the school, account, and their relationships in the current database.
4. If the problem started after deployment, inspect database connectivity, initialization results, and the mounted data volume.

Recovery check: The correct account can log in and query known data for its school. Do not recreate the data volume or import a complete historical data dump to fix login.

Maintainer reference: routing versus business failures

School WebApi uses m for the method and k for the school key. For a 404, first check the actual request and the delivered configuration.

For a 404, check the browser's actual request, reverse proxy, and endpoint path first. Once the request reaches the application, use newly generated logs to distinguish parameter, data-structure, and authentication failures. HTTP 200 does not establish business success: inspect state and the response message.

System node is not discovered

This section covers enrollment, display, and other system nodes in System Configuration. External recognition devices use their own protocol heartbeats.

1. Confirm that the terminal application is running and its network permits UDP broadcast or discovery communication with the center.
2. Refresh System Configuration and inspect any older node's last announcement time.
3. Check UDP 20785, the central discovery worker, and forwarding through VM or container networking.
4. On multi-interface hosts, verify the advertised address is neither container-only nor loopback.

If discovery works but configuration fails, check whether the center can access the terminal management interface and receive a valid response. After repair, review each configuration result and verify room retrieval or central connectivity from the terminal itself.

Enrollment cannot be completed

Symptom	Action
Floors exist but rooms are empty	Check the device user ID and its central building association, then the room data for that floor
Document cannot be read	Adjust its position and check the reader and USB permission
Submission is blocked	Complete name, document number, gender, and the on-site photo
Success message but no central record	Check school and identifier; ask an administrator to inspect the business response and stored data
Selected room was not assigned	Complete assignment in the management platform; the enrollment room selection does not confirm an assignment

The current terminal may show success for some backend business failures. Verify the person and photo in the central service. After a timeout or network interruption, check the result before retrying. See the enrollment terminal for the complete procedure.

Person is not synchronized

1. Find the person in the central service and verify the unique identifier and face photo.
2. Check building, device, and device-group relationships to confirm the intended device is in scope.
3. Confirm device heartbeats and inspect whether the synchronization task is waiting, failed, or complete.
4. Ask a maintainer to check the active push worker or the device retrieval/callback path and device response.
5. Query the person on the device and compare their identifier, photo, and latest changes.

Recovery check: Device-side information is correct and the person completes one real recognition. Restored heartbeats do not mean all queued tasks have finished.

No new display event

1. Confirm that a new recognition actually occurred and record its device and time. Exclude historical or demonstration cards shown at startup.
2. Check the display mode. In Local mode, trace device-to-display upload; in Cloud mode, trace central reception and the callback to the display.
3. Check the upload address, protocol, and receiver response. A connected-center status verifies only display-to-center heartbeat access.
4. If the receiver already has the event, inspect display event handling, photos, and display logs next.

For an online count of 0, check local or central device heartbeats according to the mode. A count of -- means no valid statistic has been obtained yet, not necessarily that no devices exist.

Recovery check: The latest card shows the same person, device, and time as the test. See the display terminal.

Unexpected unreturned results

Check the selected building, cutoff time, and name filter, then verify the person's room assignment. Next check device time, entry/exit direction, and whether all relevant events before the cutoff reached the central service.

After correcting device or data issues, run the query again. An empty list alone does not establish that everyone is in their room, and a status affected by missing events should not be treated as an on-site fact.

What to send to maintenance

Provide the time, page or terminal type, steps, expected result, actual error, and reproducible test identifier. Include relevant versions, mode, and necessary redacted log excerpts. Send real personal information, documents, faces, or secrets only through controlled channels.

After recovery, repeat the original failing operation and record the result. A restored page or completed service restart does not by itself resolve the original business problem.