Troubleshooting Virtual Nodes

Common issues and diagnostic steps for getting your virtual node online and communicating with building automation devices.

Diagnostic Commands

Check if your container is running and view recent logs:

docker compose ps
docker compose logs novant-vnode

To follow logs in real time:

docker compose logs -f novant-vnode

Issue	What to Check
No internet connectivity	Verify the host system can reach `node.novant.io`. Check firewall rules for outbound access.
License file missing or malformed	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	Run `docker compose ps` to check status. Review logs with `docker compose logs novant-vnode` for error messages.

Issue	What to Check
Wrong network or subnet	Verify the host system 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	Verify `network_mode: host` is set in your `docker-compose.yaml`. Without this, the container cannot see local devices.

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.

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 at minimum.
Network timeouts	Verify network bandwidth between the host and building automation devices is adequate.

To pull the latest image and restart:

docker compose pull
docker compose up -d

If you’re unable to resolve an issue: