Skip to content
NovaVMS Manual

Gateway will not pair with the cloud

Gateway will not pair with the cloud

Symptom

You installed the gateway agent and started the service, but the Gateways page still shows the gateway as Offline or Pending after more than two minutes. No heartbeat has landed.

Likely causes

  1. The cloud base URL in the gateway config is wrong (typo, HTTP vs HTTPS, wrong port).
  2. The one-time pairing token has expired (default lifetime is 15 minutes).
  3. Outbound firewall blocks the gateway from reaching the cloud on 443 (or 8090 for self-hosted dev).
  4. Host clock is more than 5 minutes off — token signatures fail validation.
  5. The same hardware was already paired under a different name; duplicate claim is rejected.

Fix

Re-run pairing from the web UI

  1. In the NovaVMS web UI, open Gateways.
  2. Click Add gateway. Copy the new pairing token and cloud URL.
  3. On the gateway host, paste both into the config (or use the one-line bootstrap command printed by the dialog).
  4. Restart the gateway service.

If the cloud URL is wrong

  1. Check the host can reach the cloud: curl -sI https://<cloud-host>/healthz should return 200.
  2. For self-hosted dev, confirm the port matches SERVER_ADDR in the cloud .env (default 8090, not 8080).

If the clock is skewed

  1. On the gateway host, run timedatectl (Linux) and confirm System clock synchronized: yes.
  2. If NTP is not running, install chrony or systemd-timesyncd and wait 60 seconds for the first sync.

If the gateway is a duplicate

  1. On the Gateways page, delete the stale record for this hardware.
  2. Generate a fresh pairing token and run the bootstrap command again.

Verify

  1. The Gateways page shows a green dot within 60 seconds of restart.
  2. The gateway’s Last heartbeat timestamp is under 30 seconds ago.
  3. The gateway’s host, version, and interface IPs populate in the detail panel.

If none of this worked

  • Collect the gateway log: sudo journalctl -u novavms-gateway -n 500 --no-pager.
  • Capture the clock status: timedatectl and date -u.
  • Test outbound reach: curl -vI https://<cloud-host>/healthz.
  • Attach all three to a support ticket.
  • See also: Camera does not appear in ONVIF discovery.