Clients only access `http://server:8080`. Test on the server first, then check firewall, hostname, reverse proxy, and logs.
Manual
HQControl Troubleshooting
Troubleshoot installation, access, services, PLCs, federation, and licensing layer by layer. Confirm port 8080 first, then database, Redis, modules, and devices.
Separate the layers first
Do not mix service state, PLC connectivity, IO Owner, and tag quality. Classify the issue before changing configuration.
PostgreSQL uses 15432, Redis uses 6379, and Integration Script uses local 19033. These ports are not client-facing.
PLC connectivity, IO Owner, tag quality, alarm state, and trend state must be diagnosed separately.
Services do not start after install or reboot
Confirm setup completion, service state, startup entries, and the HQControl control panel.
Open the HQControl control panel. Confirm PostgreSQL, Redis, and HQControl are running, then open the admin console on port 8080.
Run `sudo hqserverctl status`, `sudo hqserverctl health`, and `sudo hqserverctl ports`. If health fails, inspect `sudo hqserverctl logs all`.
Confirm the install path is writable, the data directory is valid, PostgreSQL has `PG_VERSION`, and config still points to 15432 and 6379.
Control panel state is wrong, autostart does not apply, or reboot does not launch services
The control panel should start, stop, repair, and open HQControl. Do not mix process state with business readiness.
A running process does not guarantee web readiness. Show process state separately from `http://hostname:8080` readiness.
After reboot, PostgreSQL and Redis should start first, HQControl should start next, and the browser entry should open last if configured.
If a service is running but the panel says stopped, fix process detection first instead of asking users to restart the main server repeatedly.
The admin console cannot open or stays not ready
Check port 8080 and the HQControl process before looking at PLC configuration.
Open `http://127.0.0.1:8080` on the server first, then `http://server-ip:8080` or `http://hostname:8080` from a client.
Only 8080 is the formal public entry. 15432, 6379, and 19033 are local runtime ports. IO State API has no separate 19031 port.
Read the HQControl log for database, Redis, migration, license, or port conflict errors.
PostgreSQL, TimescaleDB, or Redis is abnormal
Database issues affect login, migrations, alarms, trends, and configuration. Redis issues affect realtime push and hot cache.
The bundled database uses `127.0.0.1:15432`. A TimescaleDB migration error means the extension is unavailable or not loaded.
The bundled cache uses `127.0.0.1:6379`. Redis recovery should not freeze the main server.
For large tag sets, inspect runtime_status, tag queries, tag_latest, alarm queries, and trend queries with indexes and timings.
Manual connection succeeds, but the device list still shows offline
Manual diagnostics only prove the link is reachable. Runtime state also depends on IO Worker ownership and continuous collection.
For absolute mode, validate port 102, Rack, and Slot. After a successful manual check, wait for runtime-status push instead of overwriting long-running state with the button result.
For symbolic mode, validate the OPC UA endpoint such as `opc.tcp://PLC-IP:4840`, and confirm OPC UA and DB access are enabled on the PLC.
Check whether IO Worker is running, whether this site is IO Owner, whether the device is enabled, and whether bad tags block collection.
Two sites collect the same PLC, or a remote site shows no devices
Federation is directional. The same PLC must have one IO Owner, and remote pages show data only when snapshots are pushed or pulled.
A federates B means A can know and pull B. It does not mean B automatically knows A.
Owner election should consider site enabled state, device enabled state, heartbeat, PLC reachability, and priority. Do not allow two sites to collect the same PLC.
Check whether the remote site publishes runtime-status, whether devices belong to that site, and whether the federation pull API returns a device snapshot.
PLC connectivity, symbolic addressing, IO Owner, or federation is wrong
Confirm whether this site can reach the PLC, who owns IO, and whether remote federation is reachable.
Absolute addressing uses S7 TCP, usually port 102, with Host, Port, Rack, and Slot matching the PLC.
Symbolic addressing uses an OPC UA endpoint, usually `opc.tcp://PLC-IP:4840`. Do not validate it with port 102 or Rack/Slot.
Only one site should collect the same PLC. Owner failover should happen when the owner is offline; a PLC outage is a separate condition.
Service state, PLC connection state, IO Worker state, tag quality, and alarm/trend state are separate.
Online or offline activation fails
Confirm the license service URL, machine information, offline request, and imported file match.
Confirm the authorization service URL in `/settings`, code validity, instance ID, and machine fingerprint acceptance.
The `.hqreq` file must be exported from the same machine and instance. Old or cross-machine requests are rejected.
The server itself can open `/license` directly. Remote access requires the highest administrator account.