manila — Errors

Errors — manila — branch stable/2026.2

Branch stable/2026.2 @ 4fbc4b4f3688 — repository https://opendev.org/openstack/manila — analysed on 2026-10-29

This file says what a client or an operator sees when something goes wrong: the HTTP translation of exceptions (§ 1), the situations behind the most frequent errors (§ 2), the asynchronous errors that never reach the client as an HTTP status (§ 3), the defects found while building the conformance data (§ 4), the full exception catalogue (§ 5) and the key log messages (§ 6). Error responses actually observed are in [_rewrite/observed-errors_stable-2026.2.md](_rewrite/observed-errors_stable-2026.2.md) (client scenarios) and [_rewrite/observed-errors-unit-api_stable-2026.2.md](_rewrite/observed-errors-unit-api_stable-2026.2.md) (unit API tests).

1. Exception → HTTP translation

Three layers convert an exception into a response, innermost first:

1. The handler converts the exceptions it expects into webob.exc.HTTP* with an explanation (297 except … raise HTTP… blocks found by the inventory, _inventory/inventory_stable-2026.2.json http_conversions). This is where most statuses are decided, handler by handler.
2. **ResourceExceptionHandler** wraps every handler call (manila/api/openstack/wsgi.py:502-540):
   • NotAuthorized (and PolicyNotAuthorized, AdminRequired) → 403 with the exception text (manila/api/openstack/wsgi.py:518-519);
   • Invalid and every subclass → its own code (400 unless overridden) with the exception text (manila/api/openstack/wsgi.py:522-524);
   • TypeError → 400 without text, logged at ERROR (manila/api/openstack/wsgi.py:525-529): a handler called with an unexpected argument (unknown path parameter, wrong body type) looks like a client error;
   • webob HTTP exceptions → kept (manila/api/openstack/wsgi.py:533-535);
   • VersionNotFoundForAPIMethod → re-raised and turned into 404 without text by Resource.dispatch (manila/api/openstack/wsgi.py:918-925);
   • anything else propagates.
3. **FaultWrapper** (outermost Manila middleware, manila/api/middleware/fault.py:29-75) catches the rest: status = the exception's code attribute (ManilaException.code, default 500, manila/exception.py:68-71), and the message is exposed **only if the class is safe** — NotFound and its subclasses (manila/exception.py:206-209), Found (manila/exception.py:224-226) and QuotaError and its subclasses (manila/exception.py:440-444) — as "<ClassName>: <message>". Every other exception gives the bare reason phrase ("The server has either erred or is incapable of performing the requested operation." for 500). A UnicodeDecodeError becomes 400 (manila/api/middleware/fault.py:43-47).

Consequences a rewrite must reproduce:

• The same exception gives different statuses depending on the endpoint (handler conversions): ShareBusyException → 409 on backups (manila/api/v2/share_backups.py:177), 400 on replicas (manila/api/v2/share_replicas.py:258), 403 on soft delete (manila/api/v2/shares.py:442); InvalidShare → 403 on DELETE /shares/{id} (manila/api/v2/shares.py:1493-1494) but 400 elsewhere (implicit, through ResourceExceptionHandler); ServiceIsDown → 400, 409 or 500; AvailabilityZoneNotFound → 400 on share network subnet creation (manila/api/common.py:644), 404 on share and share group creation (manila/api/v2/shares.py:123-124, manila/api/v2/share_groups.py:244); NotFound → 404 in 52 places, 400 in 11 (a referenced object that does not exist, for example the resource named in a lock request → 400 "No such resource found.", manila/api/v2/resource_locks.py:181-183).
• Messages of safe exceptions carry the class name ("ShareSnapshotNotFound: Snapshot … could not be found.", "TransferNotFound: Transfer … could not be found."); messages converted by handlers do not ("Share type not found.").
• 413 responses carry Retry-After: 0 and retryAfter in the body (manila/exception.py:443, manila/api/openstack/wsgi.py:1320-1322).

2. Situations behind the main errors

The precise message of every observed error is in _rewrite/observed-errors_stable-2026.2.md; the 120 most common exceptions of the share layer have their raise sites listed in § 5.

3. Asynchronous errors

Most failures happen after the HTTP response, in manila-scheduler or manila-share. They never reach the client as a status; they show up as:

• A resource status: error (share instance, snapshot, replica, share group, backup, share server), error_deleting, extending_error, shrinking_error, shrinking_possibly_data_loss_error (legacy, never set on this branch), reverting_error, manage_error, unmanage_error, backup_restoring_error; access rules error and the instance access_rules_status: error (manila/common/constants.py:23-81).
• A user message (GET /messages, 2.37+), created by message_api.create (manila/message/api.py:43-80) with an action code and a detail code (manila/message/message_field.py:27-42, manila/message/message_field.py:61-191). Stored in the messages table, purged after [DEFAULT]/message_ttl (2592000 s, manila/message/api.py:27) by the scheduler's _clean_expired_messages. The user_message field is "<action>: <detail>", for example "allocate host: No storage could be allocated for this share request, Capabilities filter didn't succeed." (scenario no-valid-host).

The detail code is derived from the exception when not given: NoValidHost → NO_VALID_HOST, and for a NoValidHost carrying detail_data.last_filter, the filter-specific code (manila/message/message_field.py:235-252, manila/message/message_field.py:266-285).

• A notification scheduler.<method> at ERROR priority with the share id, state, method and reason when scheduling fails (manila/scheduler/manager.py:209-236).
• A log entry only: an exception raised while processing a cast is logged by the RPC server and dropped; the caller is not told. The client scenarios record those in [_rewrite/manager-errors_stable-2026.2.json](_rewrite/manager-errors_stable-2026.2.json).
• Timeouts: calls (scheduler get_pools, share connection_get_info, migration_get_progress, get_share_server_network_info…) raise oslo_messaging.MessagingTimeout after [DEFAULT]/rpc_response_timeout (60 s) → 500 for the API caller. Database outages raise DBConnectionError (oslo.db retries the connection first); deadlocks are retried 5 times on the quota and reservation functions (manila/db/sqlalchemy/api.py:1233, manila/db/sqlalchemy/api.py:1478-1530).

4. Defects found while building the conformance data

5. Exception catalogue

266 classes of manila/exception.py (the inventory lists 296 exception classes in the repository; the other 30 are driver-specific). "HTTP" is the class code inherited through the hierarchy, used by FaultWrapper when no handler converted the exception; "Raise sites" counts raise exception.<Name> outside the tests (driver code included). Exceptions imported from libraries that reach the API: oslo_messaging.MessagingTimeout (500), oslo_db.exception.DBError / DBDuplicateEntry (500 or converted to 409 by the share type, share network and quota handlers), keystoneauth1 errors from the Nova/Neutron/Cinder/Glance clients (500, logged), webob.exc.* (their own status).

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