heat — Errors

Errors — heat — branch stable/2026.2

Branch stable/2026.2 @ 5872396e548c (27.0.1) — repository https://opendev.org/openstack/heat — analysed on 2026-10-29

1. Exception → HTTP translation

• Native API. FaultWrapper (heat/api/middleware/fault.py:52-170) catches everything below it in the pipeline. It looks the exception's class name up in error_map (heat/api/middleware/fault.py:55-98), walking up the base classes until it finds a match; Exception itself maps to 500 (heat/api/middleware/fault.py:100-107). Engine exceptions arrive through oslo.messaging as dynamically created <Name>_Remote subclasses of the original class: their name is stripped of _Remote and their bases are the real Heat classes, so the same table applies (heat/api/middleware/fault.py:124-128). Body: see 01 § 1.3; error.message only for safe exceptions (all HeatExceptions).
• **webob.exc raised by handlers** (400 parse errors, 403 tenant mismatch, 404, 302, 202, 204) are wrapped in HTTPExceptionDisguise and keep their own status (heat/common/wsgi.py:355-371); non-error webob exceptions (302/202/204) are returned as responses.
• **Exceptions that are not HeatException** (oslo.messaging MessagingTimeout, RemoteError for non-Heat engine errors, KeyError, database errors leaking from the engine) → 500 with error.type set but no message (heat/api/middleware/fault.py:161-162). An engine that does not answer within rpc_response_timeout (60 s) therefore yields a 500 MessagingTimeout.
• Status not visible in the class name: ResourceTypeUnavailable → 400 but ActionNotComplete, InvalidTemplateAttribute, ResourcePropertyDependency, ResourceActionRestricted → 500, because they are absent from the map and inherit from HeatException (heat/api/middleware/fault.py:55-98). Most of them only appear wrapped in StackValidationFailed (400) during validation; raised at runtime they are resource failures.
• CFN API. No fault wrapper; handlers catch RPC errors and call map_remote_error (heat/api/aws/exception.py:285-338): 20 class names → InvalidParameterValue (400), Forbidden/NotAuthorized → AccessDenied (403), StackExists → AlreadyExists (400), ActionInProgress → InvalidAction (400), RequestLimitExceeded → RequestLimitExceeded (400), everything else → InternalFailure (500). Body: <ErrorResponse><Error><Type>Sender</Type><Code>…</Code><Message>explanation[:detail]</Message></Error></ErrorResponse> (XML; JSON with ContentType=JSON) (heat/api/aws/exception.py:42-67). Quirk: already_exists_errors and request_limit_exceeded are strings, not tuples, so ex_type in 'StackExists' is a substring test (heat/api/aws/exception.py:315-317); no Heat class name is a substring of those two today, so the outcome is right by accident. Note also that EntityNotFound is a 400 InvalidParameterValue in CFN but a 404 natively.

2. Catalogue

Computed by _rewrite/tools/heat_errors.py (the native status and the CFN code are obtained by running the real translation functions on each class; raise sites by git grep outside the tests). Full data with all raise sites: [_rewrite/errors_stable-2026.2.json](_rewrite/errors_stable-2026.2.json).

UpdateInProgress and UpdateReplace are not HeatExceptions: they are internal control flow of the convergence worker (resource locked by another engine; resource must be replaced) and never meant to reach a client (heat/common/exception.py:414-443). HEAT-E99001 is the only error code (ResourceTypeUnavailable); it prefixes the message (heat/common/exception.py:60-74) and is the only value accepted in POST /validate?ignore_errors= (heat/engine/service.py:1341-1347).

3. Situations that matter to clients

4. Asynchronous errors (statuses and events)

They are written to stack.status_reason / resource.status_reason and one event row each; the client sees them by polling or in GET …/events.

Rollback: with disable_rollback = false, a failed CREATE/UPDATE/ADOPT/RESTORE goes on to ROLLBACK_IN_PROGRESS; the failure reason stays in the events, the stack ends ROLLBACK_COMPLETE (heat/engine/stack.py:2348-2353). Clients that only look at the final state see ROLLBACK_COMPLETE, not the cause.

5. Key log messages

Source: reverse-spec-heat/02-errors_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.