Create a new gallery image definition when its platform identity must change

Source facts

Azure Compute Gallery does not permit changing an image definition’s OS type, OS state, Hyper-V generation, publisher, offer or SKU. Microsoft’s prescribed response is a new definition. A version’s source must match its definition’s generalized or specialized state and Hyper-V generation. Within one gallery, each definition must also have a unique publisher, offer and SKU combination. Microsoft Learn.

Applicability

Use this check when an image pipeline changes the source platform or preparation state but continues targeting an established definition. Keep the definition’s identity separate from the version number used for a particular build.

DSE recommendation

Treat an image-definition mismatch as a lineage design decision, not a retryable version-upload error. Have the image owner compare the proposed source with the definition before retrying publication. If a new definition is required, plan its identifier and the consumer-reference changes deliberately. Keep the old definition available under its approved lifecycle while consumers are evaluated; creating a replacement is not authorization to delete existing versions.

Verification

Publish an approved test version under the matching definition and verify its recorded state and generation. Exercise a representative consumer deployment with the intended identity and configuration inputs. Record any mismatch as a rejected publication condition rather than attempting to disguise it with another version number. Confirm that the new definition’s publisher-offer-SKU triplet is distinct within the gallery and that dependent automation uses the intended reference.

Official references

Microsoft Learn: Troubleshoot images in an Azure Compute Gallery. Source reviewed September 9, 2026.