Skip to main content

​
Overview

This guide covers the most common issues encountered when working with Polystack 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
Resolution: Delete the stuck image record and re-upload:
Delete the stuck image
Then re-upload with the --progress flag to monitor the transfer:
Re-upload with progress indicator
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
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
Resolution: Either select a flavor with a larger root disk, or reduce min_disk if it was set too conservatively:
Update min_disk property
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
Resolution: Correct the firmware and machine type properties:
Correct UEFI image properties

​
Sharing Issues

Cause: The target project has not accepted the image share.Diagnose: Check the membership status:
List image members and their status
If status shows pending, the target project must accept:
Accept the share (run as target project)
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
The owner must match your current project ID (openstack token issue -c project_id).

​
Image Status Reference

​
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.