Edge gateway troubleshooting

Symptom-based fixes for plant-site edge gateways — pairing, NATS, outbox, drift, and capacity.

Use this page when a gateway stays offline, drifts from hub config, or the outbox grows without draining.

install.bat / install.sh closes immediately or fails

Symptom	Likely cause	Fix
Window flashes and closes	Docker not running	Start Docker Desktop (Windows) or `systemctl start docker` (Linux); re-run the installer
SHA256 mismatch	Corrupt tarball, or Windows `install.bat` captured CertUtil's success line instead of the hash (`actual:` starts with `CertUtil:`)	If `actual:` is a CertUtil message, the tar is probably fine — see workaround below. Otherwise re-download the zip
`docker load` failed	Wrong architecture tarball	Match AMD64 vs ARM64 in console before download
Health never OK	Hub unreachable or wrong API URL	Fix `HUB_API_URL` in `.env.edge` (must include `/api`); open outbound HTTPS + NATS from plant

Windows SHA256 false mismatch: in the unzipped folder, with Docker Desktop running:

docker load -i datahub-edge-0.1.1-lan.tar.gz
docker compose -f edge-compose.yml --env-file .env.edge up -d

Adjust the tar name to match the file in the folder. New air-gap zips hash with PowerShell Get-FileHash instead of CertUtil.

Symptom	Likely cause	Fix
Health `503`, `paired: false`	Wrong or missing pairing code	Console → gateway detail → copy pairing code; set `PAIRING_CODE` in `.env.edge` or use Deploy to edge before first boot
Health OK but console OFFLINE	Hub API URL unreachable from plant	Use a LAN IP or DNS name the edge box can reach — not `localhost` or `host.docker.internal`
NATS never connects	NATS host/port blocked or wrong TLS	Open outbound 4222 (or TLS port); ensure `NATS_PUBLIC_URL` matches what the edge resolves; mount hub CA at `/data/ca.pem` when TLS is on
TLS verify failed	Certificate SAN mismatch	NATS cert must include the hostname/IP the edge uses — same issue when API and NATS hosts differ

Console shows Config drift when configRevision on the hub has not been applied on the edge yet.
If drift lasts more than 5 minutes, check edge logs (Gateways → detail → Logs) for manifest apply errors.
Rollback: Revisions tab → pick an earlier snapshot → Rollback (writes forward as a new revision).
Pause stops collection without revoking the token; Resume when maintenance is done.

Plant outbox depth and hub consumer lag are different problems.

What is down	Plant outbox	Where data waits	What to check
NATS or hub API (WAN/firewall)	Grows	`outbox.sqlite` on the edge box	`hubReachable` / `natsConnected` on `/healthz`; outbound 443 + 4222
`telemetry-worker` or `rule-worker` only (NATS up)	Stays low	Hub JetStream stream	Console Operations → Platform — telemetry queue pending; restart workers
Full hub stack restart	Brief spike possible, then drains	Outbox + stream	Normal after `docker compose up`; both catch up automatically
Workers stalled for days while ingest continues	Stays low until stream drops old messages	JetStream (7d / 4 GiB cap)	Fix workers before retention discards oldest events

The edge does not pause NATS drain when Postgres workers are restarting — that is intentional. JetStream is the consumer-side buffer.

High tag count with ALL publish policy generates maximum WAN load. Prefer ON_CHANGE on devices when values are stable.
Console → gateway Overview → adjust Outbox & drain policy (max rows, drain min/max dp/s) — applied via manifest without editing .env on the plant box.
Default compose limits edge CPU/RAM (EDGE_CPUS, EDGE_MEM_LIMIT) so a runaway gateway does not take the whole host.
See Edge gateway sizing for harness-based guidance (not a throughput SLA).

Stop the old container (optional: copy /data/outbox.sqlite for gap-free catch-up).
Deploy to edge on the new box — do not create a new gateway row.
Rotate token → set GATEWAY_TOKEN on the new box.
Wait for ONLINE and verify applied revision matches hub.

Service	Default host port	Direction
Edge health	8080	Local diagnostics on plant box
MQTT ingress	1883	Plant LAN → edge (push devices)
Hub API	443/3001	Outbound HTTPS from edge
NATS	4222	Outbound from edge