Skip to main content

​
Overview

This guide covers the most common issues encountered when working with Xloud Image Service — including upload failures, stuck images, launch errors caused by image properties, and shared image visibility problems.
For platform-level issues such as storage backend connectivity or Image API container failures, refer to the Image Admin Guide — Troubleshooting.

​
Upload Issues

Image stuck in 'saving' status

Cause: The upload stalled due to a client-side network interruption or the image service ran out of available storage.Diagnose: Check the image status:
Check image status
openstack image show <IMAGE_ID> -c status -c size
Resolution: Delete the stuck image record and re-upload:
Delete the stuck image
openstack image delete <IMAGE_ID>
Then re-upload with the --progress flag to monitor the transfer:
Re-upload with progress indicator
openstack image create \
  --disk-format qcow2 \
  --container-format bare \
  --file image.qcow2 \
  --progress \
  my-image
Cause: HAProxy or the load balancer is enforcing an upload size limit smaller than the image file.Resolution: Contact your platform administrator to increase the upload limit. This is a platform-level configuration change. See the Image Admin Guide — Troubleshooting for administrator instructions.
Cause: Network interruption during a large file upload. Standard HTTP PUT has no resumption capability.Resolution: Use the chunked import API for images larger than 5 GB:
Create image record
openstack image create \
  --disk-format qcow2 \
  --container-format bare \
  --import-method web-download \
  large-image
Then import from a URL hosted on a stable server — the Image Service fetches the file server-side and handles resumption internally.

​
Launch Failures

Cause: The selected flavor’s root disk is smaller than the image’s min_disk property.Diagnose: Check the image’s minimum disk setting:
Show image min_disk
openstack image show <IMAGE_ID> -c min_disk
Resolution: Either select a flavor with a larger root disk, or reduce min_disk if it was set too conservatively:
Update min_disk property
openstack image set --min-disk 20 my-image
Cause: Incorrect hw_disk_bus or hw_firmware_type property. A UEFI image launched with BIOS firmware (or vice versa) will fail to boot.Diagnose: Verify properties match the image’s actual configuration:
Show image hardware properties
openstack image show <IMAGE_ID> -c properties
Resolution: Correct the firmware and machine type properties:
Correct UEFI image properties
openstack image set \
  --property hw_firmware_type=uefi \
  --property hw_machine_type=q35 \
  <IMAGE_ID>

​
Sharing Issues

Cause: The target project has not accepted the image share.Diagnose: Check the membership status:
List image members and their status
openstack image member list <IMAGE_ID>
If status shows pending, the target project must accept:
Accept the share (run as target project)
openstack image set --accept <IMAGE_ID>
Image is now visible in the target project’s image catalog.
Cause: Only the image owner can modify its members. If the image is public, membership cannot be modified (it is already visible to all).Diagnose: Verify you are authenticated as the image owner’s project:
Check image ownership
openstack image show <IMAGE_ID> -c owner
The owner must match your current project ID (openstack token issue -c project_id).

​
Image Status Reference

StatusMeaningAction
queuedRecord created, upload not startedUpload data or delete and retry
savingUpload in progressWait, or delete if stalled
activeReady for useNo action needed
deactivatedDisabled by adminContact platform administrator
killedUpload failed with an errorDelete and re-upload

​
Next Steps

Upload an Image

Re-upload after resolving the issue using best practices.

Image Properties

Correct hardware properties to resolve launch failures.

Share Images

Review the correct sharing workflow to resolve visibility issues.

Image Admin Troubleshooting

Platform-level diagnostics for Image API and storage backend issues.