Block storage API error reference

This page documents common error responses from the Block Storage API (Cinder), with a focus on state-transition conflicts, dependency issues during delete operations, and snapshot failures. Use this reference when volume operations return unexpected status codes or when volumes enter stuck states.

The current platform release supports Cinder microversion ceiling 3.70 (Antelope).

HTTP status codes#

Example error response#

{
  "overLimit": {
    "code": 413,
    "message": "VolumeLimitExceeded: Maximum number of volumes allowed (500) exceeded.",
    "retryAfter": 0
  }
}

The status code appears both as the HTTP status and as the code field inside the response body. The body wraps the error object under a top-level key that varies by error class:

Every error body wraps the error object under one of these keys, and the inner shape stays consistent (code, message, and any optional fields). For the convention across all Quake AI APIs, see Error response format.

Volume state machine#

Volumes follow a state machine. Operations are only valid from certain states. Understanding it prevents most state-transition errors.

Valid states and transitions#

On Cinder 3.70 (Antelope), delete and extend operations against a volume in an invalid state return HTTP 400 badRequest, not 409 Conflict. The response body names the required state:

{
  "badRequest": {
    "code": 400,
    "message": "Invalid volume: Volume status must be available or error or error_restoring or error_extending or error_managing and must not be migrating, attached, belong to a group, have snapshots, awaiting a transfer, or be disassociated from snapshots after volume transfer."
  }
}

Recovery from transitional states#

If a volume is stuck in attaching, detaching, or extending for more than 10 minutes, it is likely in a stale state. Reset it:

openstack volume set --state available YOUR_VOLUME

If the volume had an attachment that no longer exists:

openstack volume set --detached YOUR_VOLUME
openstack volume set --state available YOUR_VOLUME

Delete operation errors#

"Volume is in-use"#

Cause: The volume is attached to an instance.

Resolution:

1. Check attachments:

openstack volume show YOUR_VOLUME -c attachments

1. Detach the volume:

openstack server remove volume YOUR_INSTANCE YOUR_VOLUME

1. Retry deletion.

"Volume has snapshots"#

Cause: The volume has dependent snapshots that must be deleted first.

Response: HTTP 400 badRequest. The message Invalid volume: Volume status must be available... lists have snapshots among the disallowed conditions.

Resolution:

1. List snapshots:

openstack volume snapshot list --volume YOUR_VOLUME

1. Delete each snapshot:

openstack volume snapshot delete SNAPSHOT_ID

1. Retry volume deletion.

"Volume status must be available or error"#

Cause: The volume is in a transitional state (attaching, detaching, extending).

Response: HTTP 400 badRequest. The message Invalid volume: Volume status must be available or error... lists every state the delete operation allows.

Resolution:

1. Wait for the current operation to complete.
2. If the state is stale (more than 10 minutes), reset:

openstack volume set --state available YOUR_VOLUME

1. Retry deletion.

Attach and detach errors#

Attach fails with 409#

Cause: The volume is not in available state, or is already attached to another instance.

Diagnosis:

openstack volume show YOUR_VOLUME -c status -c attachments

Resolution:

• If status is in-use: detach from the current instance first, or use multiattach if the volume type supports it.
• If status is a transitional state: wait for it to resolve.
• If status is error: reset to available and retry.

Detach fails with 409#

Cause: The volume is not in in-use state, or the attachment record does not match the specified instance.

Diagnosis:

openstack volume show YOUR_VOLUME -c status -c attachments

Resolution:

• Verify the correct instance ID in the detach command.
• If the instance no longer exists, use state reset:

openstack volume set --detached YOUR_VOLUME
openstack volume set --state available YOUR_VOLUME

Snapshot errors#

Snapshot stuck in "creating"#

Cause: The source volume is in a transitional state, or the storage backend encountered an issue.

Resolution:

1. Check source volume status:

openstack volume show YOUR_VOLUME -c status

1. If the source volume is healthy and the snapshot has been in creating for more than 10 minutes, delete and retry:

openstack volume snapshot delete STUCK_SNAPSHOT
openstack volume snapshot create --volume YOUR_VOLUME NEW_SNAPSHOT_NAME

1. For persistent failures, file a support ticket.

Snapshot quota exceeded#

openstack quota show --usage

Delete old snapshots to free capacity before retrying.

When to escalate#

Escalate to support when:

• A volume is stuck in a transitional state (attaching, detaching, extending) for more than 10 minutes and state reset does not resolve it
• Snapshots remain in creating indefinitely despite a healthy source volume and available quota
• openstack volume set --state fails or the volume reverts to an error state after reset
• Delete operations fail with errors that do not reference known dependencies (attachments, snapshots)

Escalation-ready evidence checklist#

See also#

• Block Storage API reference
• Error response format: JSON error structure, request correlation
• API rate limits: quotas vs. rate limits, /limits endpoint, 429 handling
• Retry and resilience patterns: backoff, jitter, and which errors to retry
• Volume troubleshooting runbook
• How to create a block volume