cinder — Errors

Errors — cinder — branch stable/2026.2

Branch stable/2026.2 @ c117f9cf08b4 (29.0.0-1-gc117f9cf0) — repository https://opendev.org/openstack/cinder — analysed on 2026-10-28

Cinder reports errors on two channels:

• synchronously, as an HTTP status with a fault body, when the API layer detects the problem;
• asynchronously, for everything that fails after the 202: the resource goes to an error* status and, for the main operations, a user message is recorded and exposed by GET /v3/{project_id}/messages.

Most failures of a real deployment (backend down, driver error, no capacity) are of the second kind.

1. Exception → HTTP translation

Three layers translate exceptions, from the innermost:

1. In the handler: 113 except X: raise webob.exc.HTTPY(...) conversions (inventory http_conversions). Notable ones:
   • VolumeBackendAPIException from os-initialize_connection / os-terminate_connection / os-force_detach → 500 with its message (cinder/api/contrib/volume_actions.py:175, cinder/api/contrib/volume_actions.py:197, cinder/api/contrib/admin_actions.py:142).
   • ServiceNotFound (no cinder-backup alive) on POST /backups and import → 503 (cinder/api/contrib/backups.py:198-199, cinder/api/contrib/backups.py:276).
   • InvalidVolume/InvalidSnapshot on revert → 409, while the same exceptions give 400 everywhere else (cinder/api/v3/volumes.py:279-280).
   • InvalidVolumeMetadataSize → 413 on metadata updates (cinder/api/v3/volume_metadata.py:104, cinder/api/v3/snapshot_metadata.py:111, cinder/api/v3/volumes.py:504).
   • QoSSpecsInUse on DELETE /qos-specs/{id} → 400, but 500 with force=true (cinder/api/contrib/qos_specs_manage.py:188-197).
   • VolumeTypeExists, QoSSpecsExists, GroupTypeExists, VolumeTypeAccessExists → 409; the *UpdateFailed/*AssociateFailed ones → 500.
   • POST /attachments and PUT /attachments/{id} turn any other exception into 500 "Unable to create attachment for volume" / "Unable to update the attachment" (cinder/api/v3/attachments.py:200-211).
2. **ResourceExceptionHandler** around every handler (cinder/api/openstack/wsgi.py:583-617):
   • NotAuthorized (and its subclasses PolicyNotAuthorized, AdminRequired) → 403 with the message;
   • every Invalid and NotFound subclass → its own code with its message, through ConvertedException. So Invalid subclasses can be 400, 405 (NotSupportedOperation), 409 (ResourceConflict) or 413;
   • TypeError → 400 without message, logged as an exception. A missing or unexpected keyword argument (for example DELETE /groups/{id} without a body) therefore gives 400;
   • webob.exc.HTTP* raised by a handler → kept as is.
3. **FaultWrapper** middleware (cinder/api/middleware/fault.py:45-86), for everything else:
   • status = the exception's code attribute, 500 when it has none;
   • the message is shown as "<ExceptionClass>: <message>" **only if safe = True**, which is the case for QuotaError subclasses, NotFound, ConflictNovaUsingAttachment. Otherwise the body carries webob's generic text and the real message is only in the log (Caught error: …, cinder/api/middleware/fault.py:52-54);
   • QuotaError is not logged as an exception, and its Retry-After: 0 header is kept: a quota error is 413 {"overLimit": {"code": 413, "message": "VolumeSizeExceedsAvailableQuota: …", "retryAfter": "0"}} (cinder/exception.py:614-618, cinder/api/openstack/wsgi.py:1341-1344);
   • UnicodeDecodeError → 400 (cinder/api/middleware/fault.py:46-50).

Before the handler, Resource.__call__ produces its own 400/404/406/415 (cinder/api/openstack/wsgi.py:814-866), see REST API § 1. keystonemiddleware answers 401 for a missing or invalid token, and CinderKeystoneContext returns 401 without fault body when the token has no user (cinder/api/middleware/auth.py:122-124).

What falls through to 500 with a hidden message: every CinderException that is neither Invalid, NotFound nor NotAuthorized, is not safe and has no handler conversion (for example VolumeBackendAPIException or DriverNotInitialized coming back from a synchronous RPC call), plus oslo_messaging.MessagingTimeout from a synchronous RPC call (initialize_connection, attachment_update, accept_transfer, get_capabilities…), which surfaces as 500 after [DEFAULT]/rpc_response_timeout (60 s). RPCTimeout (502) is used only by GET /capabilities/{host} (cinder/api/contrib/capabilities.py:55).

2. Statuses and the situations that produce them

3. Asynchronous errors

3.1 Resource statuses

• Volume: error (creation: no valid backend, driver failure after scheduler_max_attempts reschedules), error_deleting, error_extending, error_restoring, error_managing, error_backing-up. extend failures leave error_extending and roll back the quota reservation (cinder/volume/manager.py:3008-3070).
• Snapshot: error, error_deleting. Backup: error with fail_reason filled, error_deleting. Attachment: error_attaching, error_detaching. Group: error, error_deleting. Migration: migration_status = error. Replication: failover-error.
• At startup, the volume and backup managers move resources left in transient statuses (creating, deleting, downloading, uploading, backing-up…) by a previous run to error or back to their previous status (05 § 3.6).

3.2 User messages (GET /messages, 3.3+)

Recorded by cinder.message.api.API.create in the messages table, readable by the project, expired after [DEFAULT]/message_ttl (2,592,000 s = 30 days) and purged by the scheduler every message_reap_interval (86,400 s) (cinder/message/api.py:26-31, cinder/message/api.py:57-112, cinder/scheduler/manager.py:131-132).

• Identifier: event_id = "VOLUME_<resource>_<action>_<detail>" (cinder/message/api.py:97-105), for example VOLUME_VOLUME_001_003 = "schedule allocate volume: Could not find any available weighted backend".
• Actions (cinder/message/message_field.py): 001 schedule allocate volume, 002 attach volume, 003 copy volume to image, 004 update attachment, 005 copy image to volume, 006 unmanage volume, 007 extend volume, 008 create volume from backend storage, 009–012 snapshot create/delete/update/metadata update, 013–015 backup create/delete/restore, 016 reimage volume.
• Details: 001 unknown error, 002 driver not initialized, 003 no backend available, 004 failed to upload volume to image, 005 invalid attach mode, 006 not enough quota, 007 image larger than the volume, 008 unmanaging an encrypted volume, 009/010 Nova / driver failed to extend, 011 image signature verification failed, 012 driver failed to create the volume, 013–016 snapshot errors and snapshot busy, 017–026 backup errors (invalid state, service down, backup device, attach/detach, temporary cleanup, driver delete/restore), 027 volume status invalid, 028 Nova failed to reimage, 029 image disk format mismatch, 030 incremental backup not possible (full backup forced).
• Not covered: most other asynchronous failures (migration, retype, group operations, replication) only set a status and log.

3.3 Notifications on error

• scheduler.create_volume / scheduler.create_snapshot / scheduler.<method> at ERROR priority when scheduling fails (cinder/scheduler/manager.py:505-541, cinder/scheduler/flows/create_volume.py:109-140).
• qos_specs.*, volume_type.*, groups.reset_status error notifications from the API (cinder/api/contrib/qos_specs_manage.py:180-196, cinder/api/v3/groups.py:98-106).

3.4 RPC-level errors

• cast errors (most operations) are never seen by the caller: the manager catches them and sets an error status.
• A call that raises in the manager is re-raised in the API with the remote exception class when it is a cinder.exception (oslo.messaging serialisation of allowed_remote_exmods), otherwise as RemoteError → 500 [inferred].
• ServiceTooOld (400) when a request needs an RPC version that an older service in the deployment cannot accept (cinder/rpc.py:183-199).

4. Key log messages

5. Exception catalogue

The 218 classes of cinder/exception.py, with their status, template, and raise sites counted outside tests (core code / volume and backup drivers). "Seen by an API client as" applies the rules of § 1 when the exception reaches the API layer; exceptions raised only in managers or drivers are never seen as HTTP statuses, they become resource statuses (§ 3). 118 other classes (110 in cinder/volume/drivers/*, cinder/backup/drivers/* and cinder/zonemanager/drivers/*, plus Fault/OverLimitFault in cinder/api/openstack/wsgi.py, the NVMe target and rtstool errors and format_inspector) are in the inventory (_inventory/inventory_stable-2026.2.json, exceptions) and not repeated here.

Command %(cmd)s execution failed. %(description)s Reason: %(reason)s | 8 / 0 | cinder/image/accelerators/gzip.py:49 | 500, message hidden | cinder/exception.py:1088 | | SnapshotLimitReached | CinderException | 500 | Exceeded the configured limit of %(set_limit)s snapshots per volume. | 0 / 4 | cinder/volume/drivers/dell_emc/xtremio.py:573 | 500, message hidden | cinder/exception.py:1096 | | DriverInitiatorDataExists | Duplicate | 500 | Driver initiator data for initiator '%(initiator)s' and backend '%(namespace)s' with key '%(key)s' already exists. | 1 / 0 | cinder/db/api.py:8428 | 500, message hidden | cinder/exception.py:1101 | | RequirementMissing | CinderException | 500 | Requirement %(req)s is not installed. | 1 / 0 | cinder/ssh_utils.py:73 | 500, message hidden | cinder/exception.py:1108 | | ConflictNovaUsingAttachment | CinderException | 409 | Detach volume from instance %(instance_id)s using the Compute API | 1 / 0 | cinder/volume/api.py:2661 | 409, Class: message | cinder/exception.py:1112 |

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