Node Troubleshooting
How to verify your node is working and resolve common issues for both hardware and virtual nodes.
Checking Node Status
Log into your Novant project and go to the Nodes tab. Each node shows one of the following statuses:
| Status | Meaning |
|---|---|
| Ok | Node is connected and communicating normally. |
| Down | Node has not checked in recently. See troubleshooting below. |
Hardware Node LED Indicators
The hardware node has green and red LEDs that show its current state:
| Green LED | Red LED | Meaning |
|---|---|---|
| OFF | Solid ON | Powered on, charging super-capacitors. Boot may take several minutes if capacitors are fully depleted. |
| Slow Blink | Slow Blink | Runtime is booting and searching for an IP address. |
| Solid ON | Slow Blink | Valid IP address, but cannot reach Novant. Check internet connectivity, firewall rules, and network routing. |
| Solid ON | OFF | Operating normally. |
Virtual Node Diagnostic Commands
Check if your container is running and view recent logs:
docker compose ps
docker compose logs novant-vnodeTo follow logs in real time:
docker compose logs -f novant-vnodeCommon Issues
Node Not Coming Online
| Issue | What to Check |
|---|---|
| No internet connectivity | Verify the host or device can reach node.novant.io on
port 443. Check firewall rules for outbound HTTPS access. |
| License file missing (virtual nodes) | Confirm node.license exists at
{host_dir}/secrets/node.license and contains the full
license content from your project’s Nodes tab. |
| Container not running (virtual nodes) | Run docker compose ps to check status. Review logs with
docker compose logs novant-vnode for error messages. |
| Hardware node LED shows solid green, slow red blink | The node has a valid IP but cannot reach Novant. Check internet connectivity, firewall rules, and DNS resolution. |
Cannot Communicate with Building Devices
| Issue | What to Check |
|---|---|
| Wrong network or subnet | Verify the node is on the same network as your building automation devices. |
| Devices not reachable | Confirm devices respond to ping or other network tools from the host system. |
| Protocol mismatch | Check that protocol settings (BACnet, Modbus, etc.) match the building system configuration. |
| Network mode not set (virtual nodes) | Verify network_mode: host is set in your
docker-compose.yaml. Without this, the container cannot see
local devices. |
Outbound Proxy Issues (Virtual Nodes)
| Issue | What to Check |
|---|---|
| Node offline after adding proxy | Verify the proxy host and port are reachable from the host system. Confirm the proxy allows CONNECT tunneling and that any authentication credentials are correct. |
| Intermittent disconnects | Some proxies enforce idle timeouts that drop long-lived connections. Check your proxy server’s timeout settings. |
See Configuring an Outbound Proxy for setup details.
Performance Issues
| Issue | What to Check |
|---|---|
| Slow data collection | Check host system CPU and memory usage. Virtual nodes need at least 1-2 vCPU and 4 GB RAM. |
| Network timeouts | Verify network bandwidth between the node and building automation devices is adequate. |
Updating a Virtual Node
To pull the latest image and restart:
docker compose pull
docker compose up -dThe container will automatically restart after a firmware update if
restart: always is set in your
docker-compose.yaml.
Getting Help
If you’re unable to resolve an issue:
- Collect container logs
(
docker compose logs novant-vnode) or note LED status for hardware nodes - Note your network configuration and host system details
- Contact support@novant.io with this information