Skip to content
NovaVMS Manual

Gateway won't boot

A newly installed gateway, or one that was working and then rebooted, powers on but never shows Online in the cloud. No heartbeat ever lands. This page is for installers on-site with physical access (or out-of-band SSH) to the gateway.

Symptom

Any or all of the following:

  • The gateway has power and, for wired models, a link light on the LAN port — but the cloud Gateways page still shows the gateway as Offline.
  • SSH to the gateway fails or connects to an unexpected shell banner.
  • SSH works, but systemctl status novavms-gateway reports inactive (dead) or failed.
  • The cloud never records a first heartbeat for a newly paired gateway.

Likely causes

  1. Disk is full. Systemd refuses to start services when the data partition is full. Clip spooling, local logs, or container images often fill small SD cards.
  2. Config file corrupted or missing. A malformed gateway.yaml (truncated by a disk-full write, edited by hand with bad YAML) stops the process at startup.
  3. Systemd unit failed. The service binary is missing (broken update), permissions changed, or a dependency is not met.
  4. Bootloader or kernel corrupted. The OS itself did not come up — SSH is impossible, no login prompt on a serial console. Common after a power-loss during an OS update.
  5. Hardware failure. On Raspberry Pi gateways, SD-card wear is the dominant cause. Over many months of constant writes the card becomes read-only or unreadable.
  6. RTC battery dead. On gateways with a real-time clock coin-cell (CR2032 on many Pi HATs and mini-PCs), a dead battery means the system boots with the epoch 1970 date. TLS handshakes to the cloud then fail because the server’s certificate is “not yet valid”. Replace the coin cell and force an NTP sync on boot.

Fixes

If the disk is full

SSH to the gateway and check disk usage:

Terminal window
df -h

If any filesystem is 100% full (usually / or /var), free space:

Terminal window
sudo journalctl --vacuum-size=100M
sudo du -sh /var/lib/novavms-gateway/*

If the clip upload spool is backed up, expire old clips:

Terminal window
sudo find /var/lib/novavms/clip-spool -type f -mtime +7 -delete

Then restart the service: sudo systemctl restart novavms-gateway.

If the config file is broken

Check the unit status for a YAML parse error:

Terminal window
sudo systemctl status novavms-gateway --no-pager
sudo journalctl -u novavms-gateway -b --no-pager | tail -50

If the log shows YAML parse errors, restore the file from your deployment playbook or re-run the pairing flow with a fresh config. The config lives at /etc/novavms/gateway.yaml on the default gateway image.

If the systemd unit itself failed

Terminal window
sudo systemctl status novavms-gateway --no-pager

Look for:

  • status=203/EXEC — binary missing or not executable. Reinstall the gateway package, or re-copy the binary from your deploy target.
  • status=1/FAILURE — the process exited non-zero on startup. Read journalctl -u novavms-gateway -b for the actual error.
  • Missing dependency (for example go2rtc.service) — start the dependency first.

If the OS itself won’t come up

No SSH, no login prompt on a connected monitor or serial console. Your options:

  • Reflash the boot medium. On a Raspberry Pi, image a fresh SD card with the gateway OS and re-pair.
  • Check power. Undersized PSUs on a Pi cause boot loops. Use the manufacturer-recommended PSU.
  • Inspect the SD card / SSD. A card that throws bad block errors when imaged from another machine has failed; replace it.

If the hardware has failed

Swap the gateway unit. Pair the replacement using the Zero-touch provisioning flow if your deployment supports it, or re-run the first gateway install.

Verify the fix

  1. systemctl is-active novavms-gateway returns active.
  2. journalctl -u novavms-gateway -f shows heartbeats going out.
  3. The cloud Gateways page shows this gateway green within 60 seconds.
  4. Any cameras behind it transition back to Online within two minutes.

Still stuck?