Automation API error reference
This page documents common error responses from the Automation API (OpenStack Heat), explains what they mean operationally, and provides next-step actions. Use this reference when a stack operation fails or a stack enters a failed state.
HTTP status codes#
| Status | Meaning | Typical cause | Retryable? | Next action |
|---|---|---|---|---|
| 400 Bad Request | Template or request body is invalid | YAML/JSON syntax error, missing required parameter, invalid resource type | No | Validate template: openstack orchestration template validate --template TEMPLATE_FILE |
| 401 Unauthorized | Authentication failed | Expired token, missing X-Auth-Token header | No | Re-issue your token: openstack token issue |
| 404 Not Found | Stack or resource does not exist | Wrong stack name/ID, stack already deleted | No | List stacks: openstack stack list |
| 409 Conflict | Operation conflicts with current stack state | Stack is already being updated or deleted | Conditional | Wait for the in-progress operation to complete, then retry |
| 413 Over Limit | Quota exceeded | Resource quota reached for nested resources (instances, volumes, networks) | No | Check quota: openstack quota show --usage. See quota troubleshooting |
| 429 Too Many Requests | API rate limit exceeded | Too many requests in a short time window (gateway-enforced) | Yes | Wait and retry with exponential backoff |
| 500 Internal Server Error | Server-side failure | Heat engine error, dependency resolution failure | Yes | Retry after a brief delay. If persistent, escalate to support |
| 503 Service Unavailable | Service temporarily overloaded | Maintenance or capacity issue | Yes | Retry with exponential backoff |
Stack state machine#
Heat stacks transition through well-defined states during create, update, and delete operations. Failed states include a stack_status_reason field that explains what went wrong.
State transitions#
| Operation | In progress | Success | Failure |
|---|---|---|---|
| Create | CREATE_IN_PROGRESS | CREATE_COMPLETE | CREATE_FAILED |
| Update | UPDATE_IN_PROGRESS | UPDATE_COMPLETE | UPDATE_FAILED |
| Delete | DELETE_IN_PROGRESS | DELETE_COMPLETE | DELETE_FAILED |
| Rollback | ROLLBACK_IN_PROGRESS | ROLLBACK_COMPLETE | ROLLBACK_FAILED |
| Check | CHECK_IN_PROGRESS | CHECK_COMPLETE | CHECK_FAILED |
| Suspend | SUSPEND_IN_PROGRESS | SUSPEND_COMPLETE | SUSPEND_FAILED |
| Resume | RESUME_IN_PROGRESS | RESUME_COMPLETE | RESUME_FAILED |
Checking stack status#
bash
openstack stack show YOUR_STACK -c stack_status -c stack_status_reasonThe stack_status_reason field is the primary diagnostic artifact for failed stacks; include it in support tickets.
Inspecting stack events#
Stack events show the chronological record of every resource operation. When a stack fails, the events reveal which resource failed first.
bash
openstack stack event list YOUR_STACK --nested-depth 2Filter for failures:
bash
openstack stack event list YOUR_STACK | grep FAILEDCommon stack creation failures#
| Failure | stack_status_reason pattern | Resolution |
|---|---|---|
| Template validation error | "Property error: ... Value '...' is not an allowed value" | Fix the template parameter. Run openstack orchestration template validate --template TEMPLATE_FILE before creating. |
| Missing required parameter | "The Parameter (...) was not provided" | Supply all required parameters: openstack stack create -t template.yaml -e env.yaml --parameter key=value ... |
| Resource dependency failure | "Resource CREATE failed: ... ResourceNotFound" | A resource referenced by the template (image, flavor, network, key pair) does not exist. Verify resource IDs. |
| Quota exhaustion | "Resource CREATE failed: ... Quota exceeded" | Free resources or request a quota increase. See quota troubleshooting. |
| Timeout | "Create timed out (stack_timeout ..." | The stack took longer than the timeout. Increase --timeout or simplify the template. |
| Circular dependency | "Circular Dependency Found" | Remove the circular reference between resources in your template. |
| Unsupported resource type | "Unknown resource type: ..." | Check available resource types: openstack orchestration resource type list. The type may require a service that is not enabled. |
| Nested stack failure | "Resource CREATE failed: ... CREATE_FAILED" | Check the nested stack's events: openstack stack event list NESTED_STACK_NAME. |
Stack update errors#
Stack updates follow the same state machine as creation but have additional failure modes.
| Failure | Cause | Resolution |
|---|---|---|
| Immutable property change | The template modifies a property that requires resource replacement (e.g., changing an instance flavor without update_policy) | Heat will attempt to replace the resource. If replacement fails, the stack rolls back. |
| Update in progress | A previous update has not completed | Wait for the current operation to finish: openstack stack show YOUR_STACK -c stack_status |
| Rollback failed | The update failed and the rollback also failed, leaving the stack in ROLLBACK_FAILED | Inspect events to identify the stuck resource. You may need to manually fix the resource state or abandon the stack. |
Recovering from ROLLBACK_FAILED#
bash
openstack stack event list YOUR_STACK | grep FAILED
openstack stack resource list YOUR_STACK | grep FAILEDIf a specific resource is stuck, you can mark it for replacement on the next update:
bash
openstack stack update YOUR_STACK -t template.yaml --existing \
--clear-parameter BAD_PARAMStack abandon is disabled on Quake AI (openstack stack abandon YOUR_STACK returns ERROR: Stack Abandon is not supported.). To clear a stack whose normal delete fails, delete the underlying resources individually with the relevant openstack <service> delete commands, then drop the Heat record:
bash
openstack stack delete --yes YOUR_STACKStack delete errors#
| Failure | Cause | Resolution |
|---|---|---|
DELETE_FAILED on a resource | The resource has dependencies that prevent deletion (volume with snapshots, network with active ports) | Resolve the dependency, then retry: openstack stack delete YOUR_STACK |
Stack stuck in DELETE_IN_PROGRESS | A resource deletion is taking longer than expected | Wait. If the stack remains stuck for more than 15 minutes, check individual resource status. |
When to escalate#
Escalate to support when:
- A stack is stuck in
*_IN_PROGRESSfor more than 30 minutes with no new events ROLLBACK_FAILEDcannot be resolved by fixing the identified resource- A 500 error persists on stack operations after multiple retries
- Stack events reference internal errors you cannot interpret
Escalation-ready evidence checklist#
| Item | Command |
|---|---|
| Stack ID, name, and status | openstack stack show YOUR_STACK -c id -c stack_name -c stack_status -c stack_status_reason |
| Stack events (last 20) | openstack stack event list YOUR_STACK --sort-key event_time:desc --limit 20 |
| Failed resource details | openstack stack resource show YOUR_STACK RESOURCE_NAME |
| Template (if shareable) | openstack stack template show YOUR_STACK |
| Quota usage | openstack quota show --usage |
| Token validity | openstack token issue |
See also#
- Automation API reference: Heat endpoint reference
- Automation CLI reference: stack management commands
- How to create a Heat stack: console walkthrough
- Terraform error handling: IaC-specific debugging
- Error response format: JSON error structure, request correlation
- Retry and resilience patterns: backoff, jitter, and which errors to retry
- Quota and limits troubleshooting
- Upstream Heat API reference