Troubleshooting Offline or Failed Hosts

Troubleshoot offline hypervisor hosts in Platform9 Private Cloud Director (v2025.4+) with expert tips. Verify connectivity, hostname accuracy, and service status. Check logs for errors. If issues pers

Problem

When you see a hypervisor host in a Private Cloud Director environment that's offline, failed, or in an error state, here's how to debug the issue:

Environment

• Platform9 Private Cloud Director - v2025.4 and Higher

Procedure

1. Verify that the host has outbound network connectivity to the internet and the Private Cloud Director management plane controller:

   • $ curl -s https://<FQDN>

   • $ ping www.google.com

   • $ telnetwww.google.com443

2. If your environment has a proxy server, make sure that you have configured the Platform9 host agent installed on the host to route traffic via the proxy:

   • $ sudo bash <PATH_TO_HOSTAGENT_INSTALLER> --proxy=<PROXY_SERVER>:<PROXY_PORT>

3. Verify that the hostname on the host matches the hostname shown in the GUI.

4. The UUID given in the host_id file should match the host UUID shown on the GUI. $ sudo cat /etc/pf9/host_id.conf

5. If NTP is enabled, make sure the NTP servers are configured correctly across all the nodes within the configuration file /etc/systemd/timesyncd.conf.d/conf.d

6. Check that the Platform9 packages are installed on the host and the version which is shown on the Private Cloud Director GUI. $ sudo apt list | grep -i pf9*

7. Confirm that the host agent is running on your host:

   • $ sudo service pf9-hostagent status

   • $ sudo service pf9-ostackhost status

   • $ sudo service pf9-comms status

   • $ sudo service pf9-sidekick status

   For any errors with the above systemd service, log for journalctl logs.

8. Check the below service logs for any “errors/timeouts/warnings”, during the time of issue. verify if any recent network changes might have impacted the connectivity.

   • $ sudo cat /var/log/pf9/hostagent.log

   • $ sudo cat /var/log/pf9/ostackhost.log

   • $ sudo cat /var/log/pf9/comms/comms.log

   • $ sudo cat /var/log/pf9/sidekick/sidekick.log

9. If these steps prove insufficient to resolve the issue, kindly reach out to the Platform9 Support team for additional assistance.

Most Common causes

• Connectivity to the Private Cloud Director management plane controller is broken or unreachable.

• Dependent services are down.

• Packages are corrupted or not installed.

• NTP is not synchronized.

• Insufficient disk space available.

• Ensure that the host that you are trying to add meets the pre-requisites.