zun — Errors

Errors — zun — branch stable/2026.2

Branch stable/2026.2 @ 34135a563699 — repository https://opendev.org/openstack/zun — analysed on 2026-11-01

The inventory (_inventory/inventory_stable-2026.2.json, key exceptions) finds 155 exception classes: 151 in zun/common/exception.py, 3 in zun/common/docker_image/digest.py, and Retry in zun/scheduler/client/report.py:67. The base ZunException (zun/common/exception.py:182) carries message and code, 500 by default (zun/common/exception.py:191). Three more names are raised but defined nowhere (T9).

Evidence. Bodies come from reading the code, checked against [_rewrite/observed-errors_stable-2026.2.md](_rewrite/observed-errors_stable-2026.2.md) (221 API tests) and [_rewrite/probe_stable-2026.2.json](_rewrite/probe_stable-2026.2.json) (32 requests to the real Pecan application, without the paste pipeline). Those runs mock the scheduler and compute, so nothing here was observed against a real zun-compute. Other repositories cited: oslo.messaging 9df3fda5aa64, oslo.serialization 576f1c9ae949, python-keystoneclient b76de6a3807c.

Exception → HTTP translation

The layers, innermost first

1. **@exception.wrap_pecan_controller_exception** (zun/common/exception.py:139) sits on all controller methods under zun/api/controllers/v1/. Only RootController.get, _route, V1.get, Controller._route and _no_version_match are not wrapped (zun/api/controllers/root.py:80, zun/api/controllers/root.py:87, zun/api/controllers/v1/__init__.py:172, zun/api/controllers/v1/__init__.py:202, zun/api/controllers/base.py:98). wrap_controller_exception (zun/common/exception.py:95) decides:
   • a ZunException with code < 500 returns (zun/common/exception.py:150) {"faultcode": "Client", "faultstring": <kebab-case class name>, "status_code": N, "title": str(e), "description": str(e)}, logged at debug;
   • a ZunException with code >= 500, or any other exception (zun/common/exception.py:111), logs LOG.exception("%(correlation_id)s:%(excp)s") and returns (zun/common/exception.py:141) {"faultcode": "Server", "status_code": N, "title": <reason phrase>, "description": "Your request could not be handled because of a problem in the server. Error Correlation id is: <uuid>"}. There is no faultstring.
2. **convert_excp_to_err_code** (zun/common/exception.py:132) splits the class name: InvalidValue gives invalid-value, Base64Exception gives base-64-exception, ContainerNotFound_Remote gives container-not-found-remote (checked by running the same regular expression).
3. **NoExceptionTracebackHook.after** (zun/api/hooks.py:95, registered at zun/api/config.py:23) cuts Traceback (most recent call last): from **title only** (zun/api/hooks.py:110). It leaves description alone. With debug=True it does nothing for Client faults (zun/api/hooks.py:107).
4. **ParsableErrorMiddleware** (zun/api/middleware/parsable_error.py:25, wrapped at zun/api/app.py:45) rewrites every response whose status is not 2xx or 3xx (zun/api/middleware/parsable_error.py:60):

{"errors": [{"request_id": "", "code": "container.<faultstring lower-cased>", "status": 404,
             "title": "<title>", "detail": "<description>", "links": []}]}

The body is built from these rules:

Examples, derived by reading:

{"errors":[{"request_id":"","code":"container.container-not-found","status":404,"title":"Container abc could not be found.","detail":"Container abc could not be found.","links":[]}]}
{"errors":[{"request_id":"","code":"container.","status":500,"title":"Internal Server Error","detail":"Your request could not be handled because of a problem in the server. Error Correlation id is: 7c...","links":[]}]}

The middleware is inside api_v1, after authtoken in the pipeline (etc/zun/api-paste.ini:7). So the 401 of keystonemiddleware and the /healthcheck app do not get this format.

Errors not raised as ZunException

Version.string is OpenStack-API-Version and Version.service_string is container (zun/api/controllers/versions.py:85, zun/api/controllers/versions.py:94). Default without header: container 1.1 (zun/api/controllers/v1/__init__.py:45). latest gives 1.40 (zun/api/controllers/versions.py:137).

RPC path

Verified in zun/common/rpc.py and in the sibling checkout oslo.messaging/oslo_messaging/_drivers/common.py (same workspace, version not pinned to this branch).

• The class survives. ALLOWED_EXMODS is [zun.common.exception] (zun/common/rpc.py:36), passed as allowed_remote_exmods on the client transport (zun/common/rpc.py:44). A remote exception of that module is rebuilt with klass(*args, **kwargs), so code is the class's and isinstance still holds. This is why except exception.OperationNotSupported at zun/compute/api.py:84 works across RPC.
• The class name changes. The client gets a dynamic subclass named <Class>_Remote (oslo.messaging:oslo_messaging/_drivers/common.py:236). So the same error has code container.container-not-found from the API process and container.container-not-found-remote from the compute (T4).
• The traceback goes to the client. __str__ is overridden to return the message plus newline plus the remote traceback (oslo.messaging:oslo_messaging/_drivers/common.py:205, oslo.messaging:oslo_messaging/_drivers/common.py:235). _func_client_error puts str(excp) into both title and description (zun/common/exception.py:156). The hook cuts only title, so **detail contains the compute traceback** on every 4xx coming from a compute call (T3). A 5xx is not affected: it is obfuscated.
• **Other modules become RemoteError.** A docker.errors, neutronclient or cinderclient exception is not in the allowed modules, so oslo_messaging.RemoteError (oslo.messaging:oslo_messaging/_drivers/common.py:219) arrives: not a ZunException, so 500 container.. A rebuild failure (a class whose constructor refuses the kwargs, such as NetworkAlreadyExists, zun/common/exception.py:390) gives RemoteError too (oslo.messaging:oslo_messaging/_drivers/common.py:229).
• **translate_exception** (zun/common/utils.py:216) decorates the synchronous manager methods (zun/compute/manager.py:617, zun/compute/manager.py:807, zun/compute/manager.py:825, zun/compute/manager.py:858, zun/compute/manager.py:890, zun/compute/manager.py:927, zun/compute/manager.py:944, zun/compute/manager.py:957, zun/compute/manager.py:972, zun/compute/manager.py:990, zun/compute/manager.py:1008, zun/compute/manager.py:1022, zun/compute/manager.py:1164) and container_delete (zun/compute/manager.py:537). A ZunException passes through. Anything else is logged (Unexpected error: %s) and replaced by ZunException("Unexpected error: ..."): same 500. network_create and network_delete are calls without this decorator (zun/compute/manager.py:1282, zun/compute/manager.py:1286), so they can produce RemoteError.
• **call or cast.** Synchronous: container_show, container_logs, container_exec, container_exec_resize, container_update, container_attach, container_resize, container_top, container_get_archive, container_put_archive, container_stats, container_commit, image_search, network_create, network_delete, capsule_delete (zun/compute/rpcapi.py:75, zun/compute/rpcapi.py:102, zun/compute/rpcapi.py:108, zun/compute/rpcapi.py:115, zun/compute/rpcapi.py:124, zun/compute/rpcapi.py:133, zun/compute/rpcapi.py:138, zun/compute/rpcapi.py:143, zun/compute/rpcapi.py:148, zun/compute/rpcapi.py:155, zun/compute/rpcapi.py:161, zun/compute/rpcapi.py:166, zun/compute/rpcapi.py:185, zun/compute/rpcapi.py:199, zun/compute/rpcapi.py:213, zun/compute/rpcapi.py:218). All others are casts: errors never return. rpcapi.capsule_create and capsule_delete have no target method in the manager and no caller in zun/compute/api.py; capsules go through the container methods [inferred].
• **MessagingTimeout.** No except on it in zun/. Client created with timeout=None (zun/common/rpc_service.py:88), so [DEFAULT]/rpc_response_timeout applies (oslo.messaging default 60 s) [inferred for the default]. Effect: not a ZunException, so **500 container.**, after the delay. This includes GET /v1/containers/{id} of a container whose compute is up but stuck: only ContainerHostNotUp is caught there (zun/api/controllers/v1/containers.py:236). Exception: the image validation call on create, swallowed (zun/compute/api.py:93), so create waits for the timeout and proceeds.
• **check_container_host** (zun/compute/rpcapi.py:25) raises ContainerHostNotUp (500) before the RPC when the host's service is down. It decorates all calls on a container, and container_delete, but **no other cast** (T20).

Catalogue

"Client sees" codes are the code of the JSON body. -remote means the raise is on the compute and reaches the client through an RPC call. In that case detail carries the traceback (T3). 500 container. means the obfuscated body. Messages built by the caller are quoted in the situation. Line numbers are from grep -n on complete files. Raises of NotImplementedError are in the table after this one.

Other raises, outside the Zun hierarchy:

zun/criapi/api_pb2_grpc.py holds generated stubs raising NotImplementedError, not counted. Bare re-raises (raise, raise e) are not rows. They appear in the logs and async sections.

Classes defined but never raised

Parent classes, used only by inheritance (or by an except), are not dead code. They would never appear in a response under their own name:

Dead classes:

Also dead: exception.wrap_exception (zun/common/exception.py:56). The manager imports the other one, from zun/common/utils.py (zun/compute/manager.py:33).

DockerError and PolicyNotAuthorized have no raise statement but are raised: through utils.reraise (zun/container/docker/utils.py:49) and through exc= of oslo.policy (zun/common/policy.py:97, zun/common/policy.py:137).

External exceptions

Asynchronous errors

Status transitions

The API answers 202 (or 204 for delete) and returns before the work. utils.spawn_n (zun/common/utils.py:213) starts a greenthread with eventlet.spawn_n. An exception that leaves it reaches no one but the eventlet hub's printed traceback [inferred].

Which step writes status_reason:

NoValidHost on create

container_create in the API process runs the scheduler before the cast. The row already exists (zun/api/controllers/v1/containers.py:436), so:

• NoValidHost: status Error, status_reason "There are not enough hosts available." (fixed text; the exception's reason is lost), save, return with no raise (zun/compute/api.py:57). The client receives 202 with a body, and sees Error only on the next GET. No action row is written, as _record_action_start comes later (zun/compute/api.py:97).
• Any other scheduler exception: status Error, "Unexpected exception occurred.", re-raised: 500 (zun/compute/api.py:63).
• RequestedHostNotFound is checked before and returns 404 after destroying the row (zun/compute/api.py:120).

@wrap_exception in the manager

utils.wrap_exception (zun/common/utils.py:662, reraise=False) logs and swallows. It wraps _add_security_group, _remove_security_group, _do_container_reboot, _do_container_stop, _do_container_pause, _do_container_unpause, _do_container_kill, _do_network_detach, _do_network_attach (zun/compute/manager.py:585, zun/compute/manager.py:603, zun/compute/manager.py:634, zun/compute/manager.py:652, zun/compute/manager.py:771, zun/compute/manager.py:789, zun/compute/manager.py:872, zun/compute/manager.py:1253, zun/compute/manager.py:1271). Inside it, @wrap_container_event has already recorded the failure.

Effect: the client got 202, the status does not change (except a Docker 404, via handle_not_found), and only the action event shows the failure. Create, rebuild, start and commit are not under wrap_exception: they re-raise into the greenthread, after writing the status when the table above says so. _do_image_pull raises nothing the client can see; image_delete likewise (zun/compute/manager.py:1105, zun/compute/manager.py:1116).

Container action events

So a non-admin user learns the reason of a failed stop from nothing but "result: Error".

CNI

zun-cni is a CNI plugin on stdin and stdout talking to zun-cni-daemon over HTTP. Neither is seen by the API client. A failure reaches Docker, then zun-compute, as a create failure and so container Error [inferred].

DEL with a different CNI_CONTAINERID than registered is ignored with a warning (zun/cni/plugins/zun_cni_registry.py:99). A ContainerNotFound on DEL is ignored (zun/cni/plugins/zun_cni_registry.py:111).

WebSocket proxy

zun-wsproxy (zun/websocket/websocketproxy.py) has no HTTP error formatting of its own: it raises inside new_websocket_client (zun/websocket/websocketproxy.py:174), after the WebSocket handshake. The client sees the connection close, and the error is logged by websockify [inferred; websockify source not in the workspace].

The attach URL itself comes from GET /v1/containers/{id}/attach, which can fail with the normal HTTP errors, with NoInteractiveFlag 400 at zun/api/controllers/v1/containers.py:1059.

Key log messages

Traps

Verified by reading unless marked. Items depending on a Python semantic were checked in an isolated interpreter.

T1. Unsupported microversion is not a 406. HTTPNotAcceptableAPIVersion.__call__ does json.dump_as_bytes(err).encode("latin-1") (zun/api/http_error.py:65). dump_as_bytes returns bytes (oslo.serialization:oslo_serialization/jsonutils.py:235), and bytes has no encode: AttributeError. It happens when Pecan calls the response, and the exception leaves the application and ParsableErrorMiddleware: observed in the probes for 1.0, 1.41 and 2.1. The client then gets the WSGI server's 500 [inferred]. No test in zun/tests covers it. Even once fixed, the middleware would replace code zun.microversion-unsupported by container., and drop max_version, min_version, links (zun/api/middleware/parsable_error.py:82). The version headers set on pecan.response are passed along (zun/api/controllers/v1/__init__.py:188). A rewrite must decide: 406 with what body. The intended body is {code: "zun.microversion-unsupported", title: "Requested microversion is unsupported", max_version, min_version, links}.

T2. Wrong content type is not a 415. _do_enforce_content_types builds its message with pecan_req.content_type.decode('utf-8') (zun/api/utils.py:89). A str has no decode in Python 3: AttributeError before pecan.abort(415), observed in the probe "errors: content type". The decorator is outside wrap_pecan_controller_exception (zun/api/controllers/v1/containers.py:250, zun/api/controllers/v1/containers.py:251), so this also escapes the obfuscated-500 path: a raw 500 from the server. Includes POST with no Content-Type. Sites: zun/api/controllers/v1/containers.py:250, zun/api/controllers/v1/containers.py:268, zun/api/controllers/v1/containers.py:280, zun/api/controllers/v1/containers.py:289, zun/api/controllers/v1/containers.py:298, zun/api/controllers/v1/capsules.py:160, zun/api/controllers/v1/capsules.py:172, zun/api/controllers/v1/networks.py:66, zun/api/controllers/v1/images.py:131, zun/api/controllers/v1/registries.py:161.

T3. Compute tracebacks reach the client. Any 4xx from an RPC call has the remote traceback in detail: hook only cuts title (zun/api/hooks.py:112, zun/common/exception.py:157, oslo.messaging:oslo_messaging/_drivers/common.py:205). The class comment says the hook exists to prevent this (zun/api/hooks.py:87). Example path: GET /v1/containers/{id}/get_archive with a path absent from the container, Invalid at zun/container/docker/driver.py:966. It discloses file paths and source lines.

T4. Two codes for one error. container.conflict and container.conflict-remote are the same class. The suffix depends only on which process raised it. Conversely, NetworkAlreadyExists cannot be rebuilt over RPC: its constructor takes (field, value) only (zun/common/exception.py:390), while the rebuild passes the message plus field, value, code: TypeError, RemoteError, 500 instead of 409. Any remote message containing % fails the same way: klass(message, **kwargs) formats again (zun/common/exception.py:203) [inferred for a real message].

**T5. NoValidHost has two faces.** POST /v1/containers answers 202 then status Error (zun/compute/api.py:57). PATCH of a dedicated-CPU container answers 500 with an obfuscated body (zun/compute/manager.py:1195). NoValidHost has no code, and the reason is lost in both.

T6. Image validation never rejects. raise ImageNotFound and raise Conflict (zun/compute/api.py:79, zun/compute/api.py:81) are inside the try whose last clause is except Exception (zun/compute/api.py:93). They are logged as "Skip validation" and create continues. The comment "container create will fail with 400 status" (zun/compute/api.py:70) is wrong: the failure appears later as status Error. Only ReferenceInvalidFormat gives a 400. The existing unit test test_searching_image_exception (zun/tests/unit/compute/test_compute_api.py) confirms a search failure lets create proceed.

**T7. ImageNotFound is 400.** Parent is Invalid (zun/common/exception.py:408), so GET /v1/images/{unknown} gives 400 (zun/db/sqlalchemy/api.py:558), unlike all other lookups (404). And GET /v1/images/{not-a-uuid} is a 500: get_resource calls Image.get_by_name (zun/api/utils.py:75), which zun/objects/image.py does not define, so AttributeError. Observed: probe "errors: image name instead of a UUID".

T8. 500 where a client expects 4xx. No code, so default 500, and an obfuscated message hiding the reason:

Conversely, the reverse mistake: VolumeCreateFailed and VolumeDeleteFailed are 400 even for a Cinder 5xx (zun/common/exception.py:685, zun/common/exception.py:689).

T9. Three raised classes do not exist. exception.PciDeviceRequestFailed (zun/pci/stats.py:283), exception.ReshapeFailed (zun/scheduler/client/report.py:1207, zun/scheduler/client/report.py:1240, zun/scheduler/client/report.py:1245), exception.AllocationDeleteFailed (zun/scheduler/client/report.py:1934, zun/scheduler/client/report.py:1960). Each gives AttributeError when reached. The last matters most: a Placement failure in delete_allocation_for_container (zun/compute/manager.py:571) leaves the greenthread before container.destroy (zun/compute/manager.py:576), with the container stuck. Its status was set to Deleting by the API (zun/api/controllers/v1/containers.py:814) and is not corrected [inferred: the status reaches the DB through the compute's first save, zun/compute/manager.py:320].

T10. Wrong kwargs leave the template raw. A KeyError during formatting is caught and logged (zun/common/exception.py:204), the message stays with its %(...)s unless fatal_exception_format_errors is on:

T11. Two positional arguments. ZunException.__init__(self, message=None, **kwargs) accepts one: TypeError at zun/objects/container.py:186 (an unknown type in a DB row) and zun/cni/api.py:82 (the plugin then reports the TypeError text as its CNI error).

T12. An exception object as the message. self.message % kwargs with an exception raises TypeError (zun/common/exception.py:203; only KeyError is caught). So ConnectionFailed(e) (zun/websocket/websocketclient.py:50, zun/websocket/websocketclient.py:52, zun/websocket/websocketclient.py:54) and FailedParseStringToJson(e) (zun/api/controllers/v1/capsules.py:55) are never built.

T13. Every pre-formatted message is formatted again. Because message % kwargs runs on anything (zun/common/exception.py:203, and kwargs always has code):

**T14. except cinder_exception as e.** cinder_exception is the module cinderclient.exceptions (zun/volume/cinder_workflow.py:13). The clause is evaluated only when an exception is raised: TypeError: catching classes that do not inherit from BaseException is not allowed (zun/volume/cinder_workflow.py:186). What arrives there is VolumeDeleteFailed from zun/volume/cinder_api.py:155. So every failed delete of an auto_remove volume is a TypeError, logged at zun/compute/manager.py:220 or zun/compute/manager.py:464, or uncaught in _detach_volumes (zun/compute/manager.py:497). The intended Invalid "Delete Volume failed: %s" is unreachable.

T15. Failed commit. After a DockerError from create_image, snapshot_image stays None, the greenthread is still spawned, and snapshot_image.id raises AttributeError (zun/compute/manager.py:1033, zun/compute/manager.py:1040, zun/compute/manager.py:1044). translate_exception makes it a 500. Other failures of create_image are not DockerError: ZunException (zun/container/docker/driver.py:217), a clean 500.

T16. Detection by substring. is_not_found is '404' in str(e) (zun/container/docker/driver.py:48): a Docker 500 whose text has 404 anywhere, such as a hexadecimal container id, sets the container to Error. is_conflict matches paused in any text (zun/container/docker/driver.py:63).

T17. A handler that cannot fire. except exception.NotFound at zun/compute/compute_node_tracker.py:430 protects get_by_host_and_binary, which returns None (zun/objects/zun_service.py:67), and ZunServiceNotFound is not under NotFound anyway (zun/common/exception.py:416, zun/common/exception.py:312). If the record is absent: AttributeError on service.disabled (zun/compute/compute_node_tracker.py:424), not the graceful path of the comment.

T18. Delete action never finishes. DELETE starts an action (zun/compute/api.py:138) but _do_container_delete has no FinishAction or event (zun/compute/manager.py:545). finish_time stays null, and the same applies on failure. force also removes the row after an error: with reraise=False, _fail_container writes Error and flow continues to container.destroy (zun/compute/manager.py:549, zun/compute/manager.py:576).

T19. Silent cast failures. Stop, kill, pause, unpause, reboot, network and security group operations can fail with 202 and an unchanged status, as described under @wrap_exception (zun/common/utils.py:662). The only client-visible protection is validate_container_state (zun/common/utils.py:118), which reads the DB status, possibly stale.

T20. Same exception, different status by endpoint.

T21. CNI timeout does not give 504. With retry_on_result and stop_max_delay, the retrying library raises RetryError when time runs out (retrying installed in the venv, Retrying.call), rather than returning the last result (zun/cni/plugins/zun_cni_registry.py:80). So the ResourceNotReady branch after it (zun/cni/plugins/zun_cni_registry.py:89) is not reached on a timeout, and the daemon answers 500 through except Exception, not 504 (zun/cni/daemon/service.py:69). This was read, not run.

T22. Placement outage looks like lack of capacity. Connection or auth errors to Placement become empty candidates (zun/scheduler/client/query.py:64), then NoValidHost, then 202 and "There are not enough hosts available.". The only clue is an INFO line (zun/scheduler/client/query.py:74).

T23. Image pull reports nothing. POST /v1/images returns 202. If the image is not found, the compute logs and returns (zun/compute/manager.py:1152), and the image row stays without image_id. The Image object has no status field for a client to poll [inferred from zun/compute/manager.py:1149].

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