Troubleshoot images in an Azure Compute Gallery
Applies to: ✔️ Linux VMs ✔️ Windows VMs ✔️ Flexible scale sets ✔️ Uniform scale sets
If you have problems performing any operations on Azure Compute Gallery (formerly known as Shared Image Gallery) resources, like galleries, image definitions, and image versions, run the failing command again in debug mode. You activate debug mode by passing the --debug switch with the Azure CLI and the -Debug switch with PowerShell. After you've located the error, follow this article to troubleshoot it.
Creating or modifying a gallery
| Error Message | Cause | Mitigation |
|---|---|---|
| Gallery name is invalid. Allowed characters are English alphanumeric characters, with underscores, and periods allowed in the middle, up to 80 characters total. All other special characters, including dashes, are disallowed. | The name for the gallery does not meet the naming requirements | Choose a name that meets the following conditions: |
| The provided resource name <galleryName> has these invalid trailing characters: <character>. The name can not end with characters: <character> | The name for the gallery ends with a period or underscore | Choose a name for the gallery that meets the following conditions: |
| The provided location <region> is not available for resource type 'Microsoft.Compute/galleries'. List of available regions for the resource type is … | The region specified for the gallery is incorrect or requires an access request | Check that the region name is correct. If the region name is correct, submit an access request for the region |
| Can not delete resource before nested resources are deleted | You've tried to delete a gallery that contains at least one existing image definition. A gallery must be empty before it can be deleted | Delete all image definitions inside the gallery and then proceed to delete the gallery. If the image definition contains image versions, you must delete the image versions before you delete the image definitions |
| The gallery name <galleryName> is not unique within the subscription <subscriptionID>. Please pick another gallery name | You have an existing gallery with the same name and have tried to create another gallery with the same name | Choose a different name for the gallery |
| The resource <galleryName> already exists in location <region_1> in resource group <resourceGroup>. A resource with the same name cannot be created in location <region_2>. Please select a new resource name | You have an existing gallery with the same name and have tried to create another gallery with the same name | Choose a different name for the gallery |
Creating or modifying image definitions
| Error Message | Cause | Mitigation |
|---|---|---|
| Changing property 'galleryImage.properties.<property>' is not allowed | You tried to change the OS type, OS state, Hyper-V generation, offer, publisher, or SKU. Changing any of these properties is not permitted | Create a new image definition instead |
| The resource <galleryName/imageDefinitionName> already exists in location <region_1> in resource group <resourceGroup>. A resource with the same name cannot be created in location <region_2>. Please select a new resource name. | You have an existing image definition in the same gallery and resource group with the same name. You've tried to create another image definition with the same name and in the same gallery but in a different region. | Use a different name for the image definition, or put the image definition in a different gallery or resource group |
| The provided resource name <galleryName>/<imageDefinitionName> has these invalid trailing characters: <character>. The name can not end with characters: <character> | The <imageDefinitionName> name ends with a period or underscore. | Choose a name for the image definition that meets the following conditions: |
| The entity name <imageDefinitionName> is invalid according to its validation rule: ^[^_\W][\w-._]{0,79}(?<![-.])$"* | The <imageDefinitionName> name ends with a period or underscore. | Choose a name for the image definition that meets the following conditions: |
| Asset name galleryImage.properties.identifier.<property> is not valid. It cannot be empty. Allowed characters are uppercase or lowercase letters, digits, hyphen(-), period (.), underscore (_). Names are not allowed to end with period(.). The length of the name cannot exceed <number> characters. | The publisher, offer, or SKU value does not meet the naming requirements. | Choose a value that meets the following conditions: |
| Can not perform requested operation on nested resource. Parent resource <galleryName> not found. | There is no gallery with the name <galleryName> in the current subscription and resource group. | Check that the names of the gallery, subscription, and resource group are correct. Otherwise, create a new gallery named <galleryName> |
| The provided location <region> is not available for resource type 'Microsoft.Compute/galleries'. List of available regions for the resource type is … | The <region> name is incorrect or requires an access request. | Check that the region name is spelled correctly. You can run this command to see what regions you have access to. If the region is not in the list, submit an access request. |
| Unable to serialize value: <value> as type: 'iso-8601'., ISO8601Error: ISO 8601 time designator 'T' missing. Unable to parse datetime string <value> | The value provided to the property is not properly formatted as a date. | Provide a date in the yyyy-MM-dd, yyyy-MM-dd'T'HH:mm:sszzz, or ISO 8601-valid format. |
| Could not convert string to DateTimeOffset: <value>. Path 'properties.<property>' | The value provided to the property is not properly formatted as a date. | Provide a date in the yyyy-MM-dd, yyyy-MM-dd'T'HH:mm:sszzz, or ISO 8601-valid format |
| EndOfLifeDate must be set to a future date. | The end-of-life date property is not properly formatted as a date that's after today's date. | Provide a date in the yyyy-MM-dd, yyyy-MM-dd'T'HH:mm:sszzz, or ISO 8601-valid format |
| argument --<property>: invalid int value: <value> | <property> accepts only integer values, and <value> is not an integer. | Choose an integer value. |
| The minimum value of <property> must not be greater than the maximum value of <property>. | The minimum value provided for <property> is higher than the maximum value provided for <property>. | Change the values so that the minimum is less than or equal to the maximum. |
| Gallery image: <imageDefinitionName> identified by (publisher:<Publisher>, offer:<Offer>, sku:<SKU>) already exists. Choose a different publisher, offer, sku combination. | You've tried to create a new image definition with the same publisher, offer, and SKU triplet as an existing image definition in the same gallery. | Within a gallery, all image definitions must have a unique combination of publisher, offer, and SKU. Choose a unique combination, or choose a new gallery and create the image definition again |
| Can not delete resource before nested resources are deleted. | You've tried to delete an image definition that contains image versions. An image definition must be empty before it can be deleted. | Delete all image versions inside the image definition and then proceed to delete the image definition |
| Cannot bind parameter <property>. Cannot convert value <value> to type <propertyType>. Unable to match the identifier name <value> to a valid enumerator name. Specify one of the following enumerator names and try again: <choice_1>, <choice_2>, … | The property has a restricted list of possible values, and <value> is not one of them | Choose one of the possible <choice> values |
| Cannot bind parameter <property>. Cannot convert value <value> to type "System.DateTime" | The value provided to the property is not properly formatted as a date. | Provide a date in the yyyy-MM-dd, yyyy-MM-dd'T'HH:mm:sszzz, or ISO 8601-valid format |
| Cannot bind parameter <property>. Cannot convert value <value> to type "System.Int32" | <property> accepts only integer values, and <value> is not an integer. | Choose an integer value |
| ZRS storage account type is not supported in this region. | You've chosen standard zone-redundant storage (ZRS) in a region that does not yet support it | Change the storage account type to Premium_LRS or Standard_LRS. Check our documentation for the latest list of regions with ZRS preview enabled |
Creating or updating image versions
| Error Message | Cause | Mitigation |
|---|---|---|
| The provided location <region> is not available for resource type 'Microsoft.Compute/galleries'. List of available regions for the resource type is | The <region> name is incorrect or requires an access request | Check that the region name is spelled correctly. You can run this command to see what regions you have access to. If the region is not in the list, submit an access request |
| Can not perform requested operation on nested resource. Parent resource <galleryName/imageDefinitionName> not found | There is no gallery with the name <galleryName/imageDefinitionName> in the current subscription and resource group | Check that the names of the gallery, subscription, and resource group are correct. Otherwise, create a new gallery with the name <galleryName> and/or an image definition named <imageDefinitionName> in the indicated resource group |
| Cannot bind parameter <property>. Cannot convert value <value> to type "System.DateTime" | The value provided to the property is not properly formatted as a date | Provide a date in the yyyy-MM-dd, yyyy-MM-dd'T'HH:mm:sszzz, or ISO 8601-valid format |
| Cannot bind parameter <property>. Cannot convert value <value> to type "System.Int32" | <property> accepts only integer values, and <value> is not an integer | Choose an integer value |
| Gallery image version publishing profile regions <publishingRegions> must contain the location of image version <sourceRegion> | The location of the source image (<sourceRegion>) must be included in the <publishingRegions> list | Include <sourceRegion> in the <publishingRegions> list |
| The value <value> of parameter <property> is out of range. The value must be between <minValue> and <maxValue>, inclusive | <value> is outside the range of possible values for <property> | Choose a value that's within the range of <minValue> and <maxValue>, inclusive |
| Source <resourceID> is not found. Please check source exists, and is in the same region as gallery image version being created | There is no source located at <resourceID>, or the source at <resourceID> is not in the same region as the gallery image being created | Check that the <resourceID> value is correct and that the source region of the gallery image version is the same as the region of the <resourceID> value |
| Changing property 'galleryImageVersion.properties.storageProfile.<diskImage>.source.id' is not allowed | The source ID of a gallery image version can't be changed after creation | Ensure that the source ID is the same as the existing source ID, change the version number of the image version, or delete the current image version and try again |
| Duplicated lun numbers have been detected in the input data disks. Lun number must be unique for each data disk | When you're creating an image version by using a list of disks and/or disk snapshots, two or more disks or disk snapshots have the same LUN | Remove or change any duplicate LUNs |
| Duplicated source ids are found in the input disks. Source id should be unique for each disk | When you're creating an image version by using a list of disks and/or disk snapshots, two or more disks or disk snapshots have the same resource ID | Remove or change any duplicate disk source IDs |
| Property id <resourceID> at path 'properties.storageProfile.<diskImages>.source.id' is invalid. Expect fully qualified resource Id that start with '/subscriptions/<subscriptionID>' or '/providers/<resourceProviderNamespace>/' | The <resourceID> value is incorrectly formatted | Check that the resource ID is correct |
| The source id: <resourceID> must either be a managed image, virtual machine or another gallery image version | The <resourceID> value is incorrectly formatted | If you're using a VM, managed image, or gallery image version as the source image, check that the resource ID of the VM, managed image, or gallery image version is correct |
| The source id: <resourceID> must be a managed disk or snapshot | The <resourceID> value is incorrectly formatted | If you're using disks and/or disk snapshots as sources for the image version, check that the resource IDs of the disks and/or disk snapshots are correct |
| Cannot create Gallery Image Version from: <resourceID> since the OS State in the parent gallery image (<OsState_1>) is not <OsState_2> | The operating system state (Generalized or Specialized) does not match the operating system state specified in the image definition | Either choose a source based on a VM with the operating system state of <OsState_1> or create a new image definition for VMs based on <OsState_2> |
| The resource with id '<resourceID>' has a different Hypervisor generation ['<V#_1>'] than the parent gallery image Hypervisor generation ['<V#_2>'] | The hypervisor generation of the image version does not match the hypervisor generation specified in the image definition. The image definition operating system is <V#_1>, and the image version operating system is <V#_2> | Either choose a source with the same hypervisor generation as the image definition or create/choose a new image definition that has the same hypervisor generation as the image version |
| The resource with id '<resourceID>' has a different OS type ['<OsType_1>'] than the parent gallery image OS type generation ['<OsType _2>'] | The hypervisor generation of the image version does not match the hypervisor generation specified in the image definition. The image definition operating system is <OsType_1>, and the image version operating system is <OsType_2> | Either choose a source with the same operating system (Linux/Windows) as the image definition or create/choose a new image definition that has the same operating system generation as the image version |
| Source virtual machine <resourceID> cannot contain an ephemeral OS disk | The source at <resourceID> contains an ephemeral OS disk. The Azure Compute Gallery does not currently support ephemeral OS disks | Choose a different source based on a VM that does not use an ephemeral OS disk |
| Source virtual machine <resourceID> cannot contain disk ['<diskID>'] stored in an UltraSSD account type | The disk <diskID> is an Ultra SSD disk. The Azure Compute Gallery does not currently support Ultra SSD disks | Use a source that contains only Premium SSD, Standard SSD, and/or Standard HDD managed disks |
| Source virtual machine <resourceID> must be created from Managed Disks | The virtual machine in <resourceID> uses unmanaged disks | Use a source based on a VM that contains only Premium SSD, Standard SSD, and/or Standard HDD managed disks |
| Too many requests on source '<resourceID>'. Please reduce the number of requests on the source or wait some time before retrying | The source for this image version is currently being throttled because of too many requests | Try to create the image version later |
| The disk encryption set '<diskEncryptionSetID>' must be in the same subscription '<subscriptionID>' as the gallery resource | Disk encryption sets can be used only in the same subscription and region in which they were created | Create or use an encryption set in the same subscription and region as the image version |
| Encrypted source: '<resourceID>' is in a different subscription ID than the current gallery image version subscription '<subscriptionID_1>'. Please retry with an unencrypted source(s) or use the source's subscription '<subcriptionID_2>' to create the gallery image version | The Azure Compute Gallery does not currently support creating image versions in another subscription from another source image if the source image is encrypted | Use an unencrypted source or create the image version in the same subscription as the source |
| The disk encryption set <diskEncryptionSetID> was not found | The disk encryption might be incorrect | Check that the resource ID of the disk encryption set is correct |
| The image version name is invalid. The image version name should follow Major(int).Minor(int).Patch(int) format, for e.g: 1.0.0, 2018.12.1 etc | The valid format for an image version is three integers separated by a period. The image version name did not meet the valid format | Use an image version name that follows the format Major(int).Minor(int).Patch(int). For example: 1.0.0. or 2018.12.1 |
| The value of parameter galleryArtifactVersion.properties.publishingProfile.targetRegions.encryption.dataDiskImages.diskEncryptionSetId is invalid | The resource ID of the disk encryption set used on a data disk image uses an invalid format | Ensure that the resource ID of the disk encryption set follows the format /subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/<diskEncryptionSetName> |
| The value of parameter galleryArtifactVersion.properties.publishingProfile.targetRegions.encryption.osDiskImage.diskEncryptionSetId is invalid | The resource ID of the disk encryption set used on the OS disk image uses an invalid format | Ensure that the resource ID of the disk encryption set follows the format /subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/<diskEncryptionSetName> |
| Cannot specify new data disk image encryption lun [<number>] with a disk encryption set in region [<region>] for update gallery image version request. To update this version, remove the new lun. If you need to change the data disk image encryption settings, you must create a new gallery image version with the correct settings. | You added encryption to the data disk of an existing image version. You can't add encryption to an existing image version | Create a new gallery image version or remove the added encryption settings |
| The gallery artifact version source can only be specified either directly under storageProfile or within individual OS or data disks. One and only one source type (user image, snapshot, disk, virtual machine) can be provided | The source ID is missing | Ensure that the source ID of the source is present |
| Source was not found: <resourceID>. Please make sure the source exists | The resource ID of the source might be incorrect | Ensure that the resource ID of the source is correct |
| A disk encryption set is required for disk 'galleryArtifactVersion.properties.publishingProfile.targetRegions.encryption.osDiskImage.diskEncryptionSetId' in target region '<region_1>' since disk encryption set '<diskEncryptionSetID>' is used for the corresponding disk in region '<region_2>' | Encryption has been used on the OS disk in <region_2>, but not in <region_1> | If you're using encryption on the OS disk, use encryption in all regions |
| A disk encryption set is required for disk 'LUN <number>' in target region '<region_1>' since disk encryption set '<diskEncryptionSetID>' is used for the corresponding disk in region '<region_2>' | Encryption has been used on the data disk at LUN <number> in <region_2>, but not in <region_1> | If you're using encryption on a data disk, use encryption in all regions |
| An invalid lun [<number>] was specified in encryption.dataDiskImages. The lun must be one of the following values ['0,9'] | The LUN specified for the encryption does not match any of the LUNs for disks attached to the VM | Change the LUN in the encryption to the LUN of a data disk present in the VM |
| Duplicate luns '<number>' were specified in target region '<region>' encryption.dataDiskImages | The encryption settings used in <region> specified a LUN at least twice | Change the LUN in <region> to make sure that all the LUNs are unique in <region> |
| OSDiskImage and DataDiskImage cannot point to same blob <sourceID> | The sources for the OS disk and at least one data disk are not unique | Change the source for the OS disk and/or data disks to ensure that the OS disk as well as each data disk is unique |
| Duplicate regions are not allowed in target publishing regions | A region is listed among the publishing regions more than once | Remove the duplicate region |
| Adding new Data Disks or changing the LUN of a Data Disk in an existing Image is not allowed | An update call to the image version either contains a new data disk or has a new LUN for a disk | Use the LUNs and data disks of the existing image version |
| The disk encryption set <diskEncryptionSetID> must be in the same subscription <subscriptionID> as the gallery resource | The Azure Compute Gallery does not currently support using a disk encryption set in a different subscription | Create the image version and disk encryption set in the same subscription |
| Replication failed in this region due to 'The GalleryImageVersion source resource size 2520 exceeds the max size 2048 supported | A data disk in the source is greater than 2TB | Resize the data disk to under 2 TB |
| Operation 'Update Gallery Image Version' is not on allowed on <versionNumber>; since it is marked for deletion. You can only retry the Delete operation (or wait for an ongoing one to complete) | You attempted to update a gallery image version that is in the process of being deleted | Wait for the deletion event to complete and recreate the image version again |
| Encryption is not supported for source resource '<sourceID>'. Please use a different source resource type which supports encryption or remove encryption properties | Currently the Azure Compute Gallery only supports encryption for VMs, disks, snapshots and managed images. One of the sources provided for the image version is not in the previous list of sources that support encryption | Remove the disk encryption set from the image version and contact the support team. |
Creating or updating a VM or scale sets from an image version
| Error Message | Cause | Mitigation |
|---|---|---|
| There is no latest image version exists for "<imageDefinitionResourceID>" | The image definition you used to deploy the virtual machine does not contain any image versions that are included in latest | Ensure that there is at least one image version that has 'Exclude from latest' set to False |
| The gallery image /subscriptions/<subscriptionID>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<galleryName>/images/<imageName>/versions/<versionNumber> is not available in <region> region. Please contact image owner to replicate to this region, or change your requested region. | The version selected for deployment does not exist or does not have a replica in the indicated region | Ensure that the name of the image resource is correct and that there is at least one replica in the indicated region |
| The gallery image /subscriptions/<subscriptionID>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<galleryName>/images/<imageName> is not available in <region> region. Please contact image owner to replicate to this region, or change your requested region | The image definition selected for deployment does not have any image versions that are included in latest and also in the indicated region | Ensure that there is at least one image version in the region that has 'Exclude from latest' set to False |
| The client has permission to perform action 'Microsoft.Compute/galleries/images/versions/read' on scope <resourceID>, however the current tenant <tenantID> is not authorized to access linked subscription <subscriptionID> | The virtual machine or scale set was created through a gallery image in another tenant. You've tried to make a change to the virtual machine or scale set, but you don't have access to the subscription that owns the image | Contact the owner of the subscription of the image version to grant read access to the image version |
| The gallery image <resourceID> is not available in <region> region. Please contact image owner to replicate to this region, or change your requested region. | The VM is being created in a region that's not among the list of published regions for the gallery image. | Either replicate the image to the region or create a VM in one of the regions in the gallery image's publishing regions |
| Parameter 'osProfile' is not allowed | Admin username, password, or SSH keys were provided for a VM that was created from a specialized image version | Don't include the admin username, password, or SSH keys if you intend to create a VM from that image. Otherwise, use a generalized image version and supply the admin username, password, or SSH keys |
| Required parameter 'osProfile' is missing (null) | The VM is created from a generalized image, and it's missing the admin username, password, or SSH keys. Because generalized images don't retain the admin username, password, or SSH keys, these fields must be specified during creation of a VM or scale set | Specify the admin username, password, or SSH keys, or use a specialized image version |
| Cannot update Virtual Machine Scale Set <vmssName> as the current OS state of the VM Scale Set is Generalized which is different from the updated gallery image OS state which is Specialized | The current source image for the scale set is a generalized source image, but it's being updated with a source image that is specialized. The current source image and the new source image for a scale set must be of the same state | To update the scale set, use a generalized image version |
| Disk encryption set <diskEncryptionSetID> in Azure Compute Gallery <versionID> belongs to subscription <subscriptionID_1> and cannot be used with resource '' in subscription <subscriptionID_2> | The disk encryption set used to encrypt the image version resides in a different subscription than the subscription to host the image version | Use the same subscription for the image version and disk encryption set |
| The resource with id <vmID> has a different plan ['{"name":"<name>","publisher":"<publisher>","product":"<product>","promotionCode":"<promotionCode>"}'] than the parent gallery image plan ['null'] | The parent image definition for the image version being deployed does not have a purchase plan information | Create an image definition with the same purchase plan details from the error message and create the image version within the image definition |
| The VM or virtual machine scale set creation takes a long time | NA | Verify that the OSType of the image version that you're trying to create the VM or virtual machine scale set from has the same OSType of the source that you used to create the image version |
Creating a disk from an image version
| Error Message | Cause | Mitigation |
|---|---|---|
| The value of parameter imageReference is invalid. | You've tried to export from a gallery Image version to a disk but used a LUN position that does not exist on the image. | Check the image version to see what LUN positions are in use |
Sharing resources
The sharing of gallery, image definition, and image version resources across subscriptions is enabled using Azure role-based access control (Azure RBAC).
Replication speed
Use the --expand ReplicationStatus flag to check if the replication to all the specified target regions has finished. If not, wait for up to six hours for the job to finish. If it fails, trigger the command again to create and replicate the image version. If there are many target regions that the image version is being replicated to, consider doing the replication in phases.
Azure limits and quotas
Azure limits and quotas apply to all Azure Compute Gallery, image definition, and image version resources. Make sure you're within the limits for your subscriptions.
Next steps
Learn more about Azure Compute Galleries.