☁️ OpenStack Error: Glance Image Checksum Mismatch / Corrupt Image on Download

Exact Error Message

$ openstack image save --file ubuntu-22.04.img ubuntu-22.04
Checksum verification failed. Aborted downloading image.

Nova fails to boot from the same image and logs the underlying mismatch:

nova.virt.libvirt.imagebackend [req-...] Image ubuntu-22.04 (7a1c...) is corrupt:
  expected checksum 9f8e7d6c5b4a3928... but got 1122334455667788...
glance_store._drivers [req-...] Corrupt image download detected:
  os_hash_value mismatch for image 7a1c...

What It Means

Glance stores a checksum (checksum, an MD5) and a modern multihash (os_hash_algo + os_hash_value, usually SHA-512) for every image at upload time. When a client downloads the image — directly, or when Nova caches it to boot an instance — it recomputes the hash and compares it to the stored value. A mismatch means the bytes retrieved from the store do not match what was recorded, so Glance or Nova aborts to avoid booting a corrupt disk.

This is data-integrity protection. The image metadata may be fine while the actual bytes in the backing store (file, Ceph/RBD, or Swift) are truncated, partially written, or damaged. Occasionally the upload itself was interrupted and the stored checksum was never finalized.

Common Causes

• The upload was interrupted or truncated, so the stored bytes are incomplete.
• Storage-backend corruption (bad disk, incomplete Ceph replication, Swift object mismatch) damaged the data after upload.
• The image file was replaced or edited out-of-band in a file store without updating Glance metadata.
• A network glitch corrupted bytes in transit during upload or download.
• The image is queued/saving — metadata exists but the data was never fully committed.

Diagnostic Commands

Read the stored checksums and status for the image:

openstack image show ubuntu-22.04 -c status -c checksum -c size \
  -c os_hash_algo -c os_hash_value

Download the image bypassing client-side verification, then hash it yourself:

glance image-download --file /tmp/img.raw <image-id>
md5sum /tmp/img.raw
sha512sum /tmp/img.raw

Compare the actual size to the recorded size (a truncated upload is smaller):

ls -l /tmp/img.raw
openstack image show <image-id> -c size -f value

For a Ceph/RBD store, check the backing object’s health:

sudo rbd -p images info <image-id>
sudo ceph health detail

Step-by-Step Resolution

1. Confirm the mismatch is real by comparing your locally computed hash to Glance’s stored value:

openstack image show <image-id> -c os_hash_value -f value
sha512sum /tmp/img.raw

2. Check the image status. If it is stuck in saving/queued, the upload never completed and the image is unusable:

openstack image show <image-id> -c status -f value

3. Locate a known-good source for the image (your build artifact or the vendor’s published image) and verify its checksum before re-uploading:

sha256sum ubuntu-22.04-server-cloudimg-amd64.img

4. Delete the corrupt image so nothing boots from it, then re-create it from the verified source:

openstack image delete <image-id>
openstack image create ubuntu-22.04 \
  --disk-format qcow2 --container-format bare \
  --file ubuntu-22.04-server-cloudimg-amd64.img \
  --property hw_disk_bus=virtio

5. Confirm the new image reports active and that its checksums are populated:

openstack image show ubuntu-22.04 -c status -c checksum -c os_hash_value

6. If the storage backend itself is corrupt, repair it before re-uploading — for Ceph, resolve the unhealthy PGs first:

sudo ceph health detail

7. Boot a test instance to confirm the image is usable end to end:

openstack server create --flavor m1.small --image ubuntu-22.04 \
  --network tenant-net checksum-test
openstack server show checksum-test -c status -f value

Prevention

• Verify the source checksum (sha256sum) before every openstack image create, and script the comparison into your image pipeline.
• Never edit image files directly in a file store; always re-create through Glance so metadata and data stay consistent.
• Keep the storage backend healthy — monitor Ceph PG state, disk SMART data, and Swift replication to catch corruption early.
• Use Glance’s os_hash_value multihash rather than relying on legacy MD5 alone for integrity checks.
• Upload over stable connections and confirm status=active before publishing an image to users.

Related Errors

• Image ... is corrupt from Nova — the boot-time surfacing of the same checksum mismatch.
• Image status is not active — an image stuck in queued/saving, often the root of a “missing” checksum.
• No such file or directory in a file store — the backing data was deleted while metadata remained.
• Ceph health: PG inconsistent — backend corruption that can damage image bytes after upload.

Frequently Asked Questions

What is the difference between checksum and os_hash_value? checksum is the legacy MD5 Glance records; os_hash_value is a stronger multihash (typically SHA-512, named by os_hash_algo). Both are stored at upload and compared on download — prefer the multihash for integrity.

Can I just re-record the checksum instead of re-uploading? No. A mismatch means the stored bytes are actually wrong; updating metadata would hide corruption and let broken instances boot. Re-upload from a verified source. For scripting a verify-then-upload pipeline, the OpenStack prompts library has image-build workflows.

Why did an image that worked yesterday suddenly fail? The backing store likely developed corruption (a failing disk, unhealthy Ceph PGs, or a Swift replication gap) after the upload. Check backend health, then re-upload.

How do I know if the upload was just truncated? Compare the downloaded file size to openstack image show -c size; a smaller local file indicates a truncated or interrupted upload rather than in-place corruption.

Does deleting the corrupt image affect running instances? Instances already booted keep running from their own disks, but you should delete the bad image so nothing new boots from it, then re-create a clean copy. For more Glance fixes, see the OpenStack guides.