> For the complete documentation index, see [llms.txt](https://platform9.com/kb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://platform9.com/kb/pcd-ts/vm-deployment/troubleshooting-stack-issues.md).
# \[Outdated] Troubleshooting Heat Stack Issues
## Problem
This guide provides step-by-step instructions for troubleshooting and resolving stack issues in space.vars.product\_name.
## Environment
* Private Cloud Director Virtualization – v2025.4 and Higher
* Self-Hosted Private Cloud Director Virtualization – v2025.4 and Higher
## Procedure
When troubleshooting stack issues, follow these steps:
#### 1. Identify the Stack Status
{% tabs %}
{% tab title="command" %}
```bash
$ openstack stack list
```
{% endtab %}
{% endtabs %}
Look for statuses like `CREATE_IN_PROGRESS`, `CREATE_FAILED`, or `ROLLBACK_IN_PROGRESS`.
#### 2. Get Stack Information
{% tabs %}
{% tab title="command" %}
```bash
$ openstack stack show
```
{% endtab %}
{% endtabs %}
Review stack parameters, outputs, and overall status.
**Parameters:** Ensure required inputs like image name, flavor, or network ID are correct and exist.
**Outputs:** Confirm expected outputs (like IP addresses or resource IDs) are present. Missing outputs may indicate failed resource creation.
#### 3. Check Stack Events for Failures
{% tabs %}
{% tab title="command" %}
```bash
$ openstack stack event list
```
{% endtab %}
{% endtabs %}
#### 4. Inspect Individual Resource Status
Identify which resource caused the failure. Find out if any resource is stuck in `CREATE_IN_PROGRESS` or `CREATE_FAILED`.
{% tabs %}
{% tab title="command" %}
```bash
$ openstack stack resource list
$ openstack stack resource show
```
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Example" %}
```bash
$ openstack stack resource list
+----------------+------------------+------------------+---------------------+
| resource_name | resource_type | resource_status | updated_time |
+----------------+------------------+------------------+---------------------+
| my_instance | OS::Nova::Server | CREATE_FAILED | [TIMESTAMP] |
| my_network | OS::Neutron::Net | CREATE_COMPLETE | [TIMESTAMP] |
+----------------+------------------+------------------+---------------------+
$ openstack stack resource show my_instance
attributes: null
creation_time: '[TIMESTAMP]'
logical_resource_id: my_instance
physical_resource_id: [RESOURCE_ID]
resource_action: CREATE
resource_name: my_instance
resource_status: CREATE_FAILED
resource_status_reason: >
Resource creation failed: Quota exceeded for cores: Requested 4, but available 2.
resource_type: OS::Nova::Server
required_by:
- my_instance_floating_ip
updated_time: '[TIMESTAMP]'
```
{% endtab %}
{% endtabs %}
5. Check where did the Stack Failed. Identify the exact resource(s) and reason(s) for failure during stack creation.
{% tabs %}
{% tab title="command" %}
```bash
$ openstack stack failures list
//Sample output
Resource: my_instance
Status: CREATE_FAILED
Reason: Image could not be found.
```
{% endtab %}
{% endtabs %}
#### 6. Check Heat Component Pod Status and Logs
{% hint style="info" %}
**Info**
This step is applicable only for self-hosted PCD environments.
{% endhint %}
```
Check if the Heat components are running:
```
{% tabs %}
{% tab title="command" %}
```bash
$ kubectl get pods -n | grep heat
heat-api-xxxxxxxxxx-xxxxx 1/1 Running 0
heat-cfn-xxxxxxxxxx-xxxxx 1/1 Running 0
heat-engine-xxxxxxxxxx-xxxxx 1/1 Running 0
```
{% endtab %}
{% endtabs %}
To check for errors related to the stack or resource ID in the logs, run:
{% tabs %}
{% tab title="command" %}
```bash
$ kubectl logs -n | grep -i
$ kubectl logs -n | grep -i
```
{% endtab %}
{% endtabs %}
Look for stack tracebacks or API-related errors.
#### 7. Validate Stack Template
{% tabs %}
{% tab title="command" %}
```bash
$ openstack orchestration template validate -f
```
{% endtab %}
{% endtabs %}
Ensure the template syntax is correct before deployment.
#### 8. Check Quotas
{% tabs %}
{% tab title="command" %}
```bash
$ openstack quota show
```
{% endtab %}
{% endtabs %}
Verify if quotas are causing resource creation failures.
Check both **compute** and **network** quotas for the project, and compare them against the requested values in the stack.
key quotas to check:
* **Compute:**
* vCPUs: Requested vCPUs ≤ Available vCPUs
* RAM: Requested RAM ≤ Available RAM
* Instances: Total number of VMs within allowed limit
* **Network:**
* Ports: Requested number of ports ≤ Available quota
* Security Groups: Total security groups ≤ quota
* Floating IPs: Requested number ≤ quota
#### 9. Confirm Resource Availability
{% tabs %}
{% tab title="command" %}
```bash
$ openstack image list
$ openstack flavor list
```
{% endtab %}
{% endtabs %}
Ensure the referenced images and flavors exist.
#### 10. Check Network Connectivity
{% tabs %}
{% tab title="command" %}
```bash
$ openstack network agent list
$ openstack network show
```
{% endtab %}
{% endtabs %}
Ensure network components are operational and properly configured.
#### 11. Mark Failed Resource as Unhealthy and Attempt Stack Update
{% hint style="warning" %}
**Warning**
✅ Update the stack only if the issue is small like a typo or a missing value and everything else in the stack is working fine.
❌ Avoid updating if the stack has critical resource failures or dependencies that may cause cascading issues.
{% endhint %}
If applicable, update the stack with corrected parameters. If the issue persists, consider deleting and redeploying the stack.
{% tabs %}
{% tab title="command" %}
```bash
$ openstack stack resource mark unhealthy
$ openstack stack update --existing --template
```
{% endtab %}
{% endtabs %}
If these steps do not resolve the issue, please contact the [Platform9 Support Team](https://support.platform9.com/hc/en-us) for further assistance.
## Most common causes:
* Template syntax errors (YAML/JSON issues, missing parameters)
* Resource conflicts (duplicate names, unavailable images)
* Quota limits exceeded (compute, network, or storage)
* Networking issues (missing subnets, no floating IPs)
* Heat engine service failures
* API rate limits exceeded
* Delays in dependent resource creation
* Authentication failures (expired tokens, invalid credentials)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://platform9.com/kb/pcd-ts/vm-deployment/troubleshooting-stack-issues.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.