nova — Errors

Errors — nova — branch stable/2026.2

Branch stable/2026.2 @ 8df1922926dd (34.0.0 + 7 commits) — repository https://opendev.org/openstack/nova — analysed on 2026-10-28

Related files: REST API · interactions · async processing.

1. What the client receives

1.1 Error body

Every error produced by the compute API is a JSON object whose single key is a fault name derived from the status (nova/api/openstack/wsgi.py:876-920):

{"itemNotFound": {"code": 404, "message": "Instance 6f1c… could not be found."}}

Responses to errors still carry OpenStack-API-Version and X-OpenStack-Nova-API-Version (nova/api/openstack/wsgi.py:922-925) and X-OpenStack-Request-Id.

1.2 Exception → HTTP translation

Nova has no central exception → status table. Translation happens in three layers, innermost first:

1. In each handler, try/except exception.X: raise webob.exc.HTTPY(explanation=e.format_message()). The inventory found 345 such conversions (_inventory/inventory_stable-2026.2.json, http_conversions). The same internal exception can map to different statuses depending on the endpoint: InstanceInvalidState → 409 in 36 handlers but 400 in 2; InstanceNotFound → 404 in 26 handlers but 400 when it concerns a referenced instance; OverQuota (class code 413) → 403 everywhere in the API; NoValidHost → 400 on synchronous host checks (nova/api/openstack/compute/migrate_server.py:144). The "Converted by the API to" column of § 6 lists them per exception.
2. **@wsgi.expected_errors(codes)** around each handler (nova/api/openstack/wsgi.py:738-815): lets through only HTTP errors whose code is listed, plus Forbidden (→ 403), ValidationError (→ 400), Unauthorized (→ 401) and NotSupported (→ 400). Everything else — including a NovaException whose class code is 400 or 409 but which the handler forgot to convert — is logged as "Unexpected exception in API method" (nova/api/openstack/wsgi.py:808) and becomes 500.
3. **ResourceExceptionHandler** (nova/api/openstack/wsgi.py:369-399) wraps the result: Forbidden → 403, Invalid subclasses → their code, TypeError → 400, other webob errors → fault. Then **FaultWrapper** (nova/api/openstack/__init__.py:49) catches anything left: status from the exception's code attribute if it has one, else 500; the message is shown only if the exception is safe (nova/api/openstack/__init__.py:62-80).

Consequence for a rewrite: the class-level code of nova.exception classes is not the contract; the contract is the per-handler conversion plus the expected_errors list (both in _rewrite/api-operations_stable-2026.2.json).

1.3 Generic errors common to all endpoints

2. Errors by endpoint family

The operation table of 01 § 2 gives the expected_errors of each handler. The most significant situations:

3. RPC errors seen by the API

• RPC calls made by nova-api (reserve_block_device_name, attach_interface, console getters, diagnostics, quiesce_instance, check_can_live_migrate_* through conductor…) wait [DEFAULT]/rpc_response_timeout (60 s by default; some calls use [DEFAULT]/long_rpc_timeout, 1800 s) and raise oslo_messaging.MessagingTimeout. Handlers do not list it in expected_errors, so the client gets 500 and the operation may still complete on the host [inferred: no handler converts MessagingTimeout; checked by grep in nova/api/].
• Exceptions raised remotely by the compute come back as oslo_messaging.RemoteError unless they are registered as allowed remote exceptions; POST /servers converts RemoteError into 400 "<exc_type>: <message>" (nova/api/openstack/compute/servers.py:850-853).
• RPC casts never report errors to the API; their failures surface asynchronously (§ 4).

4. Asynchronous errors (after the 2xx response)

Instance faults. A fault row (instance_faults: code, message, details = traceback) is written by add_instance_fault_from_exc (nova/compute/utils.py:144); code is the exception's code kwarg or 500, message its formatted message (nova/compute/utils.py:80). GET /servers/{id} exposes the latest fault as fault: {code, created, message, details} when the server is in ERROR/DELETED; details is hidden from non-admins when code == 500 (nova/api/openstack/compute/views/servers.py:701-725).

Instance actions. Each async operation records an action (instance_actions) and events (instance_actions_events: event, start_time, finish_time, result, traceback); since 2.51 non-admins see failed events without traceback. This is usually the best way for a user to see which step failed.

5. Key log messages

6. Exception catalogue

539 subclasses of NovaException in nova/exception.py (the inventory counts 558 classes including non-Nova bases elsewhere). "code" is the class attribute (default 500), which only reaches the client through ResourceExceptionHandler/FaultWrapper when no handler converted it (§ 1.2). "Raised at" lists the first three raise sites in non-test code found by AST (more in _rewrite/exceptions_stable-2026.2.json). "Converted by the API to" counts the except clauses in nova/api/ that turn it into an HTTP status.

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