masakari — Errors

Errors — masakari — branch stable/2026.2

Branch stable/2026.2 @ ae41528e1ebc — repository https://opendev.org/openstack/masakari — analysed on 2026-10-28

All exception classes are in masakari/exception.py (55 classes found by the inventory, _inventory/inventory_stable-2026.2.json). The base class MasakariException carries msg_fmt (formatted with the keyword arguments) and code (HTTP status, 500 by default, masakari/exception.py:110). Messages marked observed were seen in [_rewrite/observed-errors_stable-2026.2.md](_rewrite/observed-errors_stable-2026.2.md).

Exception → HTTP translation

Four layers, innermost first:

1. The handler catches the business exceptions and raises a webob error: except exception.FailoverSegmentExists: raise exc.HTTPConflict(explanation=e.format_message()). This is the only place where FailoverSegmentExists/HostExists (which have no code, so 500) become 409.
2. **@extensions.expected_errors((…))** (masakari/api/openstack/extensions.py:380) lets through a webob error whose status is declared, a Forbidden or a ValidationError. Everything else becomes 500 masakariFault "Unexpected API Error. Please report this at https://bugs.launchpad.net/masakari/ and attach the Masakari API log if possible.\n<class '…'>", and is logged as "Unexpected exception in API method". The message reveals the Python class.
3. **ResourceExceptionHandler** (masakari/api/openstack/wsgi.py:347) turns Forbidden into 403, Invalid into its code, a TypeError into 400, and wraps webob errors into a Fault.
4. **Fault** (masakari/api/openstack/wsgi.py:1003) writes the JSON body {"<faultName>": {"code": N, "message": "…"}}. The fault name comes from the status (badRequest 400, unauthorized 401, forbidden 403, itemNotFound 404, badMethod 405, conflictingRequest 409, overLimit 413/429, badMediaType 415, notImplemented 501, serviceUnavailable 503, otherwise masakariFault), and the message is translated to the request's Accept-Language. Outside the router, **FaultWrapper** (masakari/api/openstack/__init__.py:36) maps any exception to its code (or 500). For an exception flagged safe (none in this branch) it also prefixes the class name.

Errors raised before the router (keystonemiddleware 401, MasakariKeystoneContext 401, paste 404 for an unknown path) are webob plain-text pages, not JSON (observed: "404 Not Found\n\nThe resource could not be found."). The sizelimit filter (oslo.middleware, [oslo_middleware]/max_request_body_size, 114688 bytes by default) answers 413.

Catalogue

Classes that exist but are not raised by the API or engine code in this branch: APIException, APITimeout, InvalidName, ConfigNotFound, AdminRequired, PasteAppNotFound (raised by the WSGI loader at start-up), InvalidContentType, ApiVersionsIntersect, Unauthorized, ObjectActionError (object misuse), OrphanedObjectError, DBNotAllowed, FailoverSegmentNotFoundByName.

Asynchronous errors (engine)

They never reach the POST caller: they show up in the notification's status, in the vmoves, in the recovery_workflow_details (1.1) and in the logs.

**Exceptions that are not MasakariException** (for example a KeyError in a third-party task, or a database error) escape the except clauses of masakari/engine/manager.py:99, masakari/engine/manager.py:149 and masakari/engine/manager.py:241. The notification then stays **running** until _check_expired_notifications sets it to failed after notifications_expired_interval (24 h) [inferred].

error is retried once by the periodic task and then becomes failed (05).

Key log messages

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