# Troubleshooting Offline Or Failed Hosts

When you see a hypervisor host in a <code class="expression">space.vars.product\_name</code> environment that's **offline, failed, or in an error state**, here's how to debug the issue:

## Most common causes

* Connectivity to the <code class="expression">space.vars.product\_name</code> 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 you are trying to add meets the [pre-requisites](https://platform9.com/docs/private-cloud-director/private-cloud-director/pre-requisites#host-hardware-and-configuration).

## Steps To Troubleshoot

{% stepper %}
{% step %}
**Verify outbound network connectivity**

Ensure the host can reach the internet and the <code class="expression">space.vars.product\_name</code> management plane controller:

```bash
$ curl -s https://<FQDN>
$ ping www.google.com
$ telnet www.google.com 443
```

{% endstep %}

{% step %}
**Proxy configuration (if applicable)**

If your environment uses a proxy, configure the Platform9 host agent on the host to route traffic via the proxy:

```bash
$ sudo bash <path to host agent installer> --proxy=<proxy server>:<proxy port>
```

{% endstep %}

{% step %}
**Verify hostname consistency**

Make sure the hostname on the host matches the hostname shown in the GUI.
{% endstep %}

{% step %}
**Verify host UUID**

Confirm the UUID in the `host_id` file matches the host UUID shown in the GUI:

```bash
$ sudo cat /etc/pf9/host_id.conf
```

{% endstep %}

{% step %}
**Verify NTP configuration**

If NTP is enabled, ensure NTP servers are configured correctly across nodes in:

```
/etc/systemd/timesyncd.conf.d/conf.d
```

{% endstep %}

{% step %}
**Verify Platform9 packages**

Check that Platform9 packages are installed and match the version shown in the <code class="expression">space.vars.product\_name</code> GUI:

```bash
$ sudo apt list | grep -i pf9*
```

{% endstep %}

{% step %}
**Confirm host agent services are running**

Check the status of the Platform9 services:

```bash
$ sudo service pf9-hostagent status
$ sudo service pf9-ostackhost status
$ sudo service pf9-comms status
$ sudo service pf9-sidekick status
```

{% endstep %}

{% step %}
**Inspect service logs**

Check logs for errors, timeouts, or warnings around the time of the issue and verify whether recent network changes could have impacted connectivity:

```bash
$ 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
```

{% endstep %}

{% step %}
**Contact Platform9 Support**

If these steps don't resolve the issue, reach out to the [Platform9 Support team](https://support.platform9.com/) for additional assistance.
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/2026.1/virtualized-clusters/troubleshooting-and-log-files/troubleshooting-offline-or-failed-hosts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.