Skip to content

Latest commit

 

History

History
169 lines (130 loc) · 53.9 KB

File metadata and controls

169 lines (130 loc) · 53.9 KB

🛠️ Troubleshooting

When deploying Azure resources, you may come across different error codes that stop or delay the deployment process. This section lists some of the most common errors along with possible causes and step-by-step resolutions.

Use these as quick reference guides to unblock your deployments.

⚡ Most Frequently Encountered Errors

Error Code Common Cause Full Details
InsufficientQuota Not enough quota available in subscription View Solution
MissingSubscriptionRegistration Required feature not registered in subscription View Solution
ResourceGroupNotFound RG doesn't exist or using old .env file View Solution
DeploymentModelNotSupported Model not available in selected region View Solution
DeploymentNotFound Deployment record not found or was deleted View Solution
ResourceNotFound Resource does not exist or cannot be found View Solution
SpecialFeatureOrQuotaIdRequired Subscription lacks access to specific model View Solution
ContainerAppOperationError Improperly built container image View Solution
ServiceUnavailable Service not available in selected region View Solution
BadRequest - DatabaseAccount is in a failed provisioning state Previous deployment failed View Solution
Unauthorized - Operation cannot be completed
without additional quota
Insufficient quota for requested operation View Solution
ResourceGroupBeingDeleted Resource group deletion in progress View Solution
FlagMustBeSetForRestore Soft-deleted resource requires restore flag or purge View Solution
ParentResourceNotFound Parent resource does not exist or cannot be found View Solution
AccountProvisioningStateInvalid Resource used before provisioning completed View Solution
InternalSubscriptionIsOverQuotaForSku Subscription quota exceeded for the requested SKU View Solution
InvalidResourceGroup Invalid resource group configuration View Solution
RequestDisallowedByPolicy Azure Policy blocking the requested operation View Solution

📖 Table of Contents

Subscription & Access Issues

Issue/Error Code Description Steps to Resolve
ReadOnlyDisabledSubscription Subscription is disabled or in read-only state
  • Check if you have an active subscription before starting the deployment
  • Depending on the type of the Azure Subscription, the expiration date might have been reached
  • You have to activate the Azure Subscription before creating any Azure resource
  • Refer to Reactivate a disabled Azure subscription documentation
MissingSubscriptionRegistration/
AllowBringYourOwnPublicIpAddress
Required feature not registered in subscription Enable AllowBringYourOwnPublicIpAddress Feature

Before deploying the resources, you may need to enable the Bring Your Own Public IP Address feature in Azure. This is required only once per subscription.

Steps:
  • Run the following command to register the feature:
    az feature register --namespace Microsoft.Network --name AllowBringYourOwnPublicIpAddress
  • Wait for the registration to complete. Check the status using:
    az feature show --namespace Microsoft.Network --name AllowBringYourOwnPublicIpAddress --query properties.state
  • The output should show: "Registered"
  • Once the feature is registered, refresh the provider:
    az provider register --namespace Microsoft.Network
💡 Note: Feature registration may take several minutes to complete. This needs to be done only once per Azure subscription.
Unauthorized - Operation cannot be completed without additional quota Insufficient quota for requested operation
  • Check your quota usage using:
    az vm list-usage --location "<Location>" -o table
  • To request more quota refer to VM Quota Request
CrossTenantDeploymentNotPermitted Deployment across different Azure AD tenants not allowed
  • Check tenant match: Ensure your deployment identity (user/SP) and the target resource group are in the same tenant:
    az account show
    az group show --name <RG_NAME>
  • Verify pipeline/service principal: If using CI/CD, confirm the service principal belongs to the same tenant and has permissions on the resource group
  • Avoid cross-tenant references: Make sure your Bicep doesn't reference subscriptions, resource groups, or resources in another tenant
  • Test minimal deployment: Deploy a simple resource to the same resource group to confirm identity and tenant are correct
  • Guest/external accounts: Avoid using guest users from other tenants; use native accounts or SPs in the tenant
RequestDisallowedByPolicy Azure Policy blocking the requested operation
  • This typically indicates that an Azure Policy is preventing the requested action due to policy restrictions in your subscription
  • For more details and guidance on resolving this issue, refer to: RequestDisallowedByPolicy
SpecialFeatureOrQuotaIdRequired Subscription lacks access to specific Azure OpenAI models This error occurs when your subscription does not have access to certain Azure OpenAI models.

Example error message:
SpecialFeatureOrQuotaIdRequired: The current subscription does not have access to this model 'Format:OpenAI,Name:o3,Version:2025-04-16'.

Resolution:
To gain access, submit a request using the official form:
👉 Azure OpenAI Model Access Request

You'll need to use this form if you require access to the following restricted models:
  • gpt-5
  • o3
  • o3-pro
  • deep research
  • reasoning summary
  • gpt-image-1
Once your request is approved, redeploy your resource.
ResourceProviderError Resource provider not registered in subscription
  • This error occurs when the resource provider is not registered in your subscription
  • To register it, refer to Register Resource Provider documentation

Quota & Capacity Limitations

Issue/Error Code Description Steps to Resolve
InternalSubscriptionIsOverQuotaForSku/
ManagedEnvironmentProvisioningError
Subscription quota exceeded for the requested SKU Quotas are applied per resource group, subscriptions, accounts, and other scopes. For example, your subscription might be configured to limit the number of vCPUs for a region. If you attempt to deploy a virtual machine with more vCPUs than the permitted amount, you receive an error that the quota was exceeded.

For PowerShell, use the Get-AzVMUsage cmdlet to find virtual machine quotas:
Get-AzVMUsage -Location "West US"

Based on available quota you can deploy application otherwise, you can request for more quota
ServiceQuotaExceeded Free tier service quota limit reached for Azure AI Search This error occurs when you attempt to deploy an Azure AI Search service but have already reached the free tier quota limit for your subscription. Each Azure subscription is limited to one free tier Search service.

Example error message:
ServiceQuotaExceeded: Operation would exceed 'free' tier service quota. You are using 1 out of 1 'free' tier service quota.

Common causes:
  • Already have a free tier Azure AI Search service in the subscription
  • Previous deployment created a free tier Search service that wasn't deleted
  • Attempting to deploy multiple environments with free tier Search services

Resolution:
  • Option 1: Delete existing free tier Search service:
    az search service list --query "[?sku.name=='free']" -o table
    az search service delete --name <service-name> --resource-group <rg-name> --yes
  • Option 2: Upgrade to a paid SKU:
    Modify your Bicep/ARM template to use basic, standard, or higher SKU instead of free
  • Option 3: Use existing Search service:
    Reference the existing free tier Search service in your deployment instead of creating a new one
  • Request quota increase:
    Submit a support request with issue type 'Service and subscription limits (quota)' and quota type 'Search' via Azure Quota Request

Reference:
InsufficientQuota Not enough quota available in subscription
  • Check if you have sufficient quota available in your subscription before deployment
  • To verify, refer to the quota_check file for details
MaxNumberOfRegionalEnvironmentsInSubExceeded Maximum Container App Environments limit reached for region This error occurs when you attempt to create more Azure Container App Environments than the regional quota limit allows for your subscription. Each Azure region has a specific limit on the number of Container App Environments that can be created per subscription.

Common Causes:
  • Deploying to regions with low quota limits (e.g., Sweden Central allows only 1 environment)
  • Multiple deployments without cleaning up previous environments
  • Exceeding the standard limit of 15 environments in most major regions

Resolution:
  • Delete unused environments in the target region, OR
  • Deploy to a different region with available capacity, OR
  • Request quota increase via Azure Support

Reference:
SkuNotAvailable Requested SKU not available in selected location or zone This error occurs when the resource SKU you've selected (such as VM size) isn't available for the target location or availability zone.

In this deployment, the jumpbox VM defaults to Standard_D2s_v5. While this size is available in most regions, certain regions or zones may not support it.

Resolution:
  • Check SKU availability for your target region:
    az vm list-skus --location <region> --size Standard_D2s --output table
  • Override the VM size if the default isn't available in your region:
    azd env set AZURE_ENV_VM_SIZE Standard_D2s_v4
  • Recommended alternatives (all support accelerated networking + Premium SSD):
    - Standard_D2s_v4 — previous gen, identical pricing
    - Standard_D2as_v5 — AMD-based, similar pricing
    - Standard_D2s_v3 — older gen, widely available
  • Avoid A-series VMs (e.g., Standard_A2m_v2) — they do not support accelerated networking or Premium SSD, which are required by this deployment

Reference:
Conflict - No available instances to satisfy this request Azure App Service has insufficient capacity in the region This error occurs when Azure App Service doesn't have enough available compute instances in the selected region to provision or scale your app.

Common Causes:
  • High demand in the selected region (e.g., East US, West Europe)
  • Specific SKUs experiencing capacity constraints (Free, Shared, or certain Premium tiers)
  • Multiple rapid deployments in the same region

Resolution:
  • Wait and Retry (15-30 minutes): azd up
  • Deploy to a New Resource Group (Recommended for urgent cases):
    <br>azd down --force --purge<br>azd up<br>
  • Try a Different Region:
    Update region in main.bicep or azure.yaml to a less congested region (e.g., westus2, centralus, northeurope)
  • Use a Different SKU/Tier:
    If using Free/Shared tier, upgrade to Basic or Standard
    Check SKU availability: az appservice list-locations --sku <sku-name>

Reference: Azure App Service Plans

Resource Group & Deployment Management

Issue/Error Code Description Steps to Resolve
ResourceGroupNotFound Specified resource group does not exist Option 1:
  • Go to Azure Portal
  • Click on "Resource groups" option
    alt text
  • Search for the resource group in the search bar. If it exists, you can proceed
    alt text

Option 2:
  • This error can occur if you deploy using the same .env file from a previous deployment
  • Create a new environment before redeploying:
    azd env new <env-name>
ResourceGroupBeingDeleted Resource group is currently being deleted Steps:
  • Go to Azure Portal
  • Go to resource group option and search for targeted resource group
  • If the resource group is being deleted, you cannot use it. Create a new one or use a different resource group
DeploymentActive Another deployment is already in progress in this resource group
  • This occurs when a deployment is already in progress and another deployment is triggered in the same resource group
  • Cancel the ongoing deployment before starting a new one
  • Do not initiate a new deployment until the previous one is completed
DeploymentCanceled Deployment was canceled before completion
  • Check deployment history:
    Go to Azure Portal → Resource Group → Deployments
    Review the detailed error message
  • Identify the root cause:
    Dependent resource failed to deploy
    Validation error occurred
    Manual cancellation was triggered
  • Validate template:
    az deployment group validate --resource-group <rg-name> --template-file main.bicep
  • Check resource limits/quotas
  • Fix the failed dependency
  • Retry deployment:
    az deployment group create --resource-group <rg-name> --template-file main.bicep

💡 Note: DeploymentCanceled is a wrapper error — check inner errors in deployment logs
DeploymentCanceled(user.canceled) User manually canceled the deployment
  • Deployment was manually canceled by the user (Portal, CLI, or pipeline)
  • Check deployment history and logs to confirm who/when it was canceled
  • If accidental, retry the deployment
  • For pipelines, ensure no automation or timeout is triggering cancellation
  • Use deployment locks or retry logic to prevent accidental cancellations
DeploymentNotFound Deployment record not found or was deleted
  • This occurs when the user deletes a previous deployment along with the resource group, then redeploys the same RG with the same environment name but in a different location
  • Do not change the location when redeploying a deleted RG, OR
  • Use new names for the RG and environment during redeployment
ResourceGroupDeletionTimeout Resource group deletion exceeded timeout limit
  • Some resources may be stuck deleting or have dependencies; check RG resources and status
  • Ensure no resource locks or Azure Policies are blocking deletion
  • Retry deletion via CLI/PowerShell:
    az group delete --name <RG_NAME> --yes --no-wait
  • Check Activity Log to identify failing resources
  • Escalate to Azure Support if deletion is stuck

Regional & Location Issues

Issue/Error Code Description Steps to Resolve
LocationNotAvailableForResourceType Resource type not supported in selected region This error occurs when you attempt to deploy a resource to a region that does not support that specific resource type or SKU.

Resolution:
  • Verify resource availability by region:
    az provider show --namespace <provider-namespace> --query "resourceTypes[?resourceType=='<resource-type>'].locations" -o table
  • Check Azure Products by Region:
    Azure Products by Region
  • Supported regions for this deployment:
    • australiaeast
    • centralus
    • eastasia
    • eastus2
    • japaneast
    • northeurope
    • southeastasia
    • uksouth
  • Redeploy:
    azd up
InvalidResourceLocation Cannot change region for already deployed resources This error occurs when you attempt to modify the location/region of a resource that has already been deployed. Azure resources cannot change regions after creation.

Resolution:
  • Option 1: Delete and Redeploy:
    azd down --force --purge
    after purge redeploy app azd up
  • Option 2: Create new environment with different region:
    azd env new <new-env-name>
    azd env set AZURE_LOCATION <new-region>
    azd up
  • Option 3: Keep existing deployment:
    Revert configuration files to use the original region

⚠️ Important: Backup critical data before deleting resources.

Reference: Move Azure resources across regions
ServiceUnavailable/ResourceNotFound Service unavailable or restricted in selected region
ResourceOperationFailure/
ProvisioningDisabled
Resource provisioning restricted or disabled in region
  • This error occurs when provisioning of a resource is restricted in the selected region. It usually happens because the service is not available in that region or provisioning has been temporarily disabled
  • Regions are restricted to guarantee compatibility with paired regions and replica locations for data redundancy and failover scenarios based on articles Azure regions list and Azure Database for MySQL Flexible Server - Azure Regions
  • If you need to use the same region, you can request a quota or provisioning exception. Refer Quota Request for more details
RedundancyConfigurationNotAvailableInRegion Redundancy configuration not supported in selected region
  • This issue happens when you try to create a Storage Account with a redundancy configuration (e.g., Standard_GRS) that is not supported in the selected Azure region
  • Example: Creating a storage account with GRS in italynorth will fail with error:
    az storage account create -n mystorageacct123 -g myResourceGroup -l italynorth --sku Standard_GRS --kind StorageV2
  • To check supported SKUs for your region:
    az storage account list-skus -l italynorth -o table
  • Use a supported redundancy option (e.g., Standard_LRS) in the same region or deploy the Storage Account in a region that supports your chosen redundancy
  • For more details, refer to Azure Storage redundancy documentation
NoRegisteredProviderFound Unsupported API version for resource type in specified location This error occurs when you attempt to deploy an Azure resource using an API version that is not supported for the specified resource type and location.

Example error message:
NoRegisteredProviderFound: No registered resource provider found for location 'westeurope' and API version '2020-06-30' for type 'searchServices'. The supported api-versions are '2014-07-31-Preview, 2015-02-28, 2015-08-19, 2019-10-01-Preview, 2020-03-13, 2020-08-01, 2020-08-01-Preview, 2021-04-01-Preview, 2021-06-06-Preview, 2022-09-01, 2023-11-01, 2024-03-01-Preview, 2024-06-01-Preview, 2025-02-01-Preview, 2025-05-01'.

Common causes:
  • Using an outdated or invalid API version in Bicep/ARM templates
  • Referencing an Azure Verified Module (AVM) that uses a deprecated API version
  • Copy-pasting old template code with legacy API versions
  • The API version was never valid (typo or incorrect version number)

Resolution:
  • Update the API version in your Bicep/ARM template to a supported version listed in the error message. For example, change:
    resource searchService 'Microsoft.Search/searchServices@2020-06-30'
    to:
    resource searchService 'Microsoft.Search/searchServices@2025-05-01'
  • Check supported API versions for a resource type:
    az provider show --namespace Microsoft.Search --query "resourceTypes[?resourceType=='searchServices'].apiVersions" -o table
  • Use the latest stable API version when possible (avoid preview versions for production)
  • Update Azure Verified Modules (AVM) to their latest versions if using external modules
  • Validate your template before deployment:
    az deployment group validate --resource-group <rg-name> --template-file main.bicep

Reference:

Resource Naming & Validation

Issue/Error Code Description Steps to Resolve
ResourceNameInvalid Resource name violates naming convention rules
  • Ensure the resource name is within the allowed length and naming rules defined for that specific resource type, you can refer Resource Naming Convention document
Workspace Name - InvalidParameter Workspace name does not meet required format To avoid this errors in workspace ID follow below rules:
  • Must start and end with an alphanumeric character (letter or number)
  • Allowed characters: a–z, 0–9, - (hyphen)
  • Cannot start or end with a hyphen -
  • No spaces, underscores (_), periods (.), or special characters
  • Must be unique within the Azure region & subscription
  • Length: 3–33 characters (for AML workspaces)
VaultNameNotValid Key Vault name does not meet naming requirements In this template Vault name will be unique everytime, but if you trying to hard code the name then please make sure below points:
  • Check name length - Ensure the Key Vault name is between 3 and 24 characters
  • Validate allowed characters - The name can only contain letters (a–z, A–Z) and numbers (0–9). Hyphens are allowed, but not at the beginning or end, and not consecutive (--)
  • Ensure proper start and end - The name must start with a letter. The name must end with a letter or digit (not a hyphen)
  • Test with a new name - Example of a valid vault name: ✅ cartersaikeyvault1, ✅ securevaultdemo, ✅ kv-project123
BadRequest: Dns record under zone Document is already taken DNS record name already in use This error can occur only when user hardcoding the CosmosDB Service name. To avoid this you can try few below suggestions:
  • Verify resource names are globally unique
  • If you already created an account/resource with same name in another subscription or resource group, check and delete it before reusing the name
  • By default in this template we are using unique prefix with every resource/account name to avoid this kind for errors

Resource Identification & References

Issue/Error Code Description Steps to Resolve
LinkedInvalidPropertyId/
ResourceNotFound/
DeploymentOutputEvaluationFailed/
CanNotRestoreANonExistingResource/
The language expression property array index is out of bounds
Invalid or non-existent resource ID reference
  • Before using any resource ID, ensure it follows the correct format
  • Verify that the resource ID you are passing actually exists
  • Make sure there are no typos in the resource ID
  • Verify that the provisioning state of the existing resource is Succeeded by running the following command to avoid this error while deployment or restoring the resource:
    az resource show --ids <Resource ID> --query "properties.provisioningState"
  • Sample Resource IDs format:
    Log Analytics Workspace Resource ID: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}
    Azure AI Foundry Project Resource ID: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{name}
  • You may encounter the error The language expression property array index '8' is out of bounds if the resource ID is incomplete. Please ensure your resource ID is correct and contains all required information, as shown in sample resource IDs
  • For more information refer Resource Not Found errors solutions
ParentResourceNotFound Parent resource does not exist or cannot be found
PrincipalNotFound Principal ID does not exist in Azure AD tenant This error occurs when the principal ID (Service Principal, User, or Group) specified in a role assignment or deployment does not exist in the Azure Active Directory tenant. It can also happen due to replication delays right after creating a new principal.

Example causes:
  • The specified Object ID is invalid or belongs to another tenant
  • The principal was recently created but Azure AD has not yet replicated it
  • Attempting to assign a role to a non-existing or deleted Service Principal/User/Group

How to fix:
  • Verify that the principal ID is correct and exists in the same directory/tenant:
    az ad sp show --id <object-id>
  • If the principal was just created, wait a few minutes and retry
  • Explicitly set the principalType property (ServicePrincipal, User, or Group) in your ARM/Bicep template to avoid replication delays
  • If the principal does not exist, create it again before assigning roles
  • For more details, see Azure PrincipalType documentation
SubscriptionDoesNotHaveServer Referenced SQL Server does not exist in subscription This issue happens when you try to reference an Azure SQL Server (Microsoft.Sql/servers) that does not exist in the selected subscription.

It can occur if:
  • The SQL server name is typed incorrectly
  • The SQL server was deleted but is still being referenced
  • You are working in the wrong subscription context
  • The server exists in a different subscription/tenant where you don't have access

Reproduce:
Run an Azure CLI command with a non-existent server name:
az sql db list --server sql-doesnotexist --resource-group myResourceGroup
or
az sql server show --name sql-caqfrhxr4i3hyj --resource-group myResourceGroup

Resolution:
  • Verify the SQL Server name exists in your subscription:
    az sql server list --output table
  • Make sure you are targeting the correct subscription:
    az account show
    az account set --subscription <subscription-id>
  • If the server was deleted, either restore it (if possible) or update references to use a valid existing server

Network & Infrastructure Configuration

Issue/Error Code Description Steps to Resolve
NetcfgSubnetRangeOutsideVnet Subnet IP range outside virtual network address space
  • Ensure the subnet's IP address range falls within the virtual network's address space
  • Always validate that the subnet CIDR block is a subset of the VNet range
  • For Azure Bastion, the AzureBastionSubnet must be at least /27
  • Confirm that the AzureBastionSubnet is deployed inside the VNet
DisableExport_PublicNetworkAccessMustBeDisabled Public network access must be disabled when export is disabled
  • Check container source: Confirm whether the deployment is using a Docker image or Azure Container Registry (ACR)
  • Verify ACR configuration: If ACR is included, review its settings to ensure they comply with Azure requirements
  • Check export settings: If export is disabled in ACR, make sure public network access is also disabled
  • Redeploy after fix: Correct the configuration and redeploy. This will prevent the Conflict error during deployment
  • For more information refer ACR Data Loss Prevention document
VMSizeIsNotPermittedToEnableAcceleratedNetworking VM size does not support accelerated networking This error occurs when you attempt to enable accelerated networking on a VM size that does not support it.

Note: This solution uses Standard_D2s_v5 which fully supports accelerated networking, so this error should not occur with the default configuration.

How to reproduce:
  • Create or deploy a VM (e.g., via ARM/Bicep) with an unsupported size like Standard_A2m_v2 or Standard_B2ms
  • In the network interface configuration, set "enableAcceleratedNetworking": true
  • Submit the request → Azure throws VMSizeIsNotPermittedToEnableAcceleratedNetworking

Resolution:
NetworkSecurityGroupNotCompliantForAzureBastionSubnet / SecurityRuleParameterContainsUnsupportedValue NSG rules blocking required Azure Bastion ports This error occurs when the Network Security Group (NSG) attached to AzureBastionSubnet explicitly denies inbound TCP ports 443 and/or 4443, which Azure Bastion requires for management and tunneling.

How to reproduce:
  • Deploy the template with enablePrivateNetworking=true so the virtualNetwork module creates AzureBastionSubnet and a Network Security Group that denies ports 443 and 4443
  • Attempt to deploy Azure Bastion into that subnet
  • During validation, Bastion detects the deny rules and fails with NetworkSecurityGroupNotCompliantForAzureBastionSubnet

Resolution:
  • Allow inbound TCP 443 and 4443 on AzureBastionSubnet by updating or removing the NSG deny rules
  • Alternatively, deploy Bastion to a subnet without restrictive NSG rules
  • For more details, refer to Azure Bastion NSG requirements
RouteTableCannotBeAttachedForAzureBastionSubnet Route table attached to Azure Bastion subnet This error occurs because Azure Bastion subnet (AzureBastionSubnet) has a platform restriction that prevents route tables from being attached.

How to reproduce:
  • In virtualNetwork.bicep, add attachRouteTable: true to the AzureBastionSubnet configuration:
    { name: 'AzureBastionSubnet', addressPrefixes: ['10.0.10.0/26'], attachRouteTable: true }
  • Add a Route Table module to the template
  • Update subnet creation to attach route table conditionally:
    routeTableResourceId: subnet.?attachRouteTable == true ? routeTable.outputs.resourceId : null
  • Deploy the template → Azure throws RouteTableCannotBeAttachedForAzureBastionSubnet

Resolution:
  • Remove the attachRouteTable: true flag from AzureBastionSubnet configuration
  • Ensure no route table is associated with AzureBastionSubnet
  • Route tables can only be attached to other subnets, not AzureBastionSubnet
  • For more details, refer to Azure Bastion subnet requirements

Configuration & Property Errors

Issue/Error Code Description Steps to Resolve
InvalidRequestContent Deployment contains unrecognized or missing required values
  • The deployment values either include values that aren't recognized, or required values are missing. Confirm the values for your resource type
  • You can refer Invalid Request Content error documentation
Conflict - Cannot use the SKU Basic with File Change Audit for site File Change Audit not supported on Basic SKU
  • This error happens because File Change Audit logs aren't supported on Basic SKU App Service Plans
  • Upgrading to Premium/Isolated SKU (supports File Change Audit), or
  • Disabling File Change Audit in Diagnostic Settings if you must stay on Basic
  • Always cross-check the supported log types before adding diagnostic logs to your Bicep templates
AccountPropertyCannotBeUpdated Read-only property cannot be modified after creation The property isHnsEnabled (Hierarchical Namespace for Data Lake Gen2) is read-only and can only be set during storage account creation. Once a storage account is created, this property cannot be updated. Trying to update it via ARM template, Bicep, CLI, or Portal will fail.

Resolution:
  • Create a new storage account with isHnsEnabled=true if you require hierarchical namespace
  • Migration may be needed if you already have data
  • Refer to Storage Account Update Restrictions for more details
Conflict - Local authentication is disabled App Configuration store has local authentication disabled but application is using local auth mode This error occurs when your Azure App Configuration store has local authentication disabled (disableLocalAuth: true) but your application is trying to access it using connection strings or access keys instead of Azure AD/Managed Identity authentication.

Example error message:
The operation cannot be performed because the configuration store is using local authentication mode and local authentication is disabled. To enable access to data plane resources while local authentication is disabled, please use pass-through authentication mode.

Common causes:
  • App Configuration store deployed with disableLocalAuth: true for security compliance
  • Application code using connection strings instead of Managed Identity
  • SDK client initialized with access keys rather than DefaultAzureCredential

Resolution:
  • Option 1: Update application to use Managed Identity (Recommended)
    python<br>from azure.identity import DefaultAzureCredential<br>from azure.appconfiguration import AzureAppConfigurationClient<br><br>credential = DefaultAzureCredential()<br>client = AzureAppConfigurationClient(<br> endpoint="https://your-appconfig.azconfig.io",<br> credential=credential<br>)<br>
  • Option 2: Re-enable local authentication (Not recommended for production)
    Set disableLocalAuth: false in your Bicep/ARM template
  • Ensure proper RBAC assignment: Verify that the Managed Identity has App Configuration Data Reader or App Configuration Data Owner role assigned

Reference:
PropertyChangeNotAllowed Immutable VM property cannot be changed after creation This error occurs when you attempt to modify an immutable property (such as osProfile.adminUsername) on an existing VM.

Cause (Azure Limitation):
Once a VM is created, the osProfile.adminUsername property is immutable and cannot be changed. If you modify the VM username or password in the template and redeploy, this issue will occur.

Resolution:
  • Delete the existing deployment and redeploy with new credentials:
    azd down --force --purge
  • Set new credentials before redeployment:
    azd env set AZURE_ENV_VM_ADMIN_USERNAME "newusername"
    azd env set AZURE_ENV_VM_ADMIN_PASSWORD "NewSecurePassword123!"
  • Redeploy:
    azd up

Note: Some VM properties are immutable by design. Always plan credential and configuration changes before initial deployment.

Resource State & Provisioning

Issue/Error Code Description Steps to Resolve
AccountProvisioningStateInvalid Resource used before provisioning completed
  • The AccountProvisioningStateInvalid error occurs when you try to use resources while they are still in the Accepted provisioning state
  • This means the deployment has not yet fully completed
  • To avoid this error, wait until the provisioning state changes to Succeeded
  • Only use the resources once the deployment is fully completed
BadRequest - DatabaseAccount is in a failed provisioning state because the previous attempt to create it was not successful Database account failed to provision previously
  • This error occurs when a user attempts to redeploy a resource that previously failed to provision
  • To resolve the issue, delete the failed deployment first, then start a new deployment
  • For guidance on deleting a resource from a Resource Group, refer to the following link: Delete an Azure Cosmos DB account
ServiceDeleting Cannot provision service because deletion is still in progress This error occurs when you attempt to create an Azure Search service with the same name as one that is currently being deleted. Azure Search services have a soft-delete period during which the service name remains reserved.

Common causes:
  • Deleting a Search service and immediately trying to recreate it with the same name
  • Rapid redeployments using the same service name in Bicep/ARM templates
  • The deletion operation is asynchronous and takes several minutes to complete

Resolution:
  • Wait for deletion to complete (10-15 minutes) before redeploying
  • Use a different service name - append timestamp or unique identifier to the name
  • Implement retry logic with exponential backoff as suggested in the error message
  • Check deletion status before recreating:
    az search service show --name <service-name> --resource-group <rg-name>
  • For Bicep deployments, ensure your naming strategy includes unique suffixes to avoid conflicts
  • For more details, refer to Azure Search service limits
FailedIdentityOperation / ManagedEnvironmentScheduledForDelete Identity operation failed due to pending delete or resource conflict This error occurs when you attempt to create or update an Azure Container Apps Managed Environment while it has a pending delete operation or the resource already exists in a conflicting state.

Example error messages:
FailedIdentityOperation: Identity operation for resource failed with error 'Failed to perform resource identity operation. Status: 'Conflict'. Response: 'Request specified that resource is new, but resource already exists. This may be due to a pending delete operation, try again later.'

ManagedEnvironmentScheduledForDelete: The environment 'cae-xxx' is under deletion. Please retry the creation with new name or wait for the deletion completed.

Common causes:
  • Deleting a Container Apps Environment and immediately trying to recreate it with the same name
  • Rapid redeployments using azd up without waiting for previous cleanup
  • Resource group deletion in progress while attempting to redeploy
  • Previous deployment failed or was canceled, leaving resources in an inconsistent state
  • Concurrent deployments targeting the same resources

Resolution:
  • Wait for deletion to complete (5-15 minutes) before redeploying:
    az containerapp env show --name <env-name> --resource-group <rg-name> --query "properties.provisioningState"
  • Check environment status: If status is ScheduledForDelete or Deleting, wait for it to complete
  • Use a new environment name: Create a new environment with a different name or use a new resource group:
    azd env new <new-env-name>
    azd up
  • Force delete and wait: If the environment is stuck, try force deletion:
    az containerapp env delete --name <env-name> --resource-group <rg-name> --yes
    Wait for deletion to complete before redeploying
  • Delete associated Container Apps first: If the environment has apps, delete them before the environment:
    az containerapp list --environment <env-name> --resource-group <rg-name> -o table
    az containerapp delete --name <app-name> --resource-group <rg-name> --yes
  • Use unique naming: Implement timestamp or unique suffix in your naming strategy to avoid conflicts

Reference:
BadRequest - Parent account does not provision correctly Parent AI Services/Cognitive Services account failed to provision This error occurs when a child resource (such as an AI project, model deployment, or other dependent resource) attempts to be created on a parent Cognitive Services/AI Services account that has failed to provision or is in an incomplete state.

Example error message:
Parent account does not provision correctly, please retry creating the account.

Common causes:
  • Parent AI Services account provisioning failed due to quota, region, or configuration issues
  • Using restore: true flag when no soft-deleted resource exists to restore
  • Network or transient errors during parent account creation
  • Invalid configuration on the parent account (e.g., invalid SKU, unsupported region)
  • Previous deployment of the parent account was interrupted or canceled

Resolution:
  • Check parent account status:
    az cognitiveservices account show --name <account-name> --resource-group <rg-name> --query "properties.provisioningState"
  • Delete failed parent account and redeploy:
    az cognitiveservices account delete --name <account-name> --resource-group <rg-name>
    Then run: azd up
  • If using restore flag incorrectly: Ensure restore: false in your Bicep template unless you specifically need to restore a soft-deleted resource
  • Check for soft-deleted resources:
    az cognitiveservices account list-deleted
  • Purge soft-deleted resources if needed:
    az cognitiveservices account purge --name <account-name> --resource-group <rg-name> --location <location>
  • Verify quota and region availability: Ensure you have sufficient quota and the service is available in your selected region

Reference:

Miscellaneous

Issue/Error Code Description Steps to Resolve
DeploymentModelNotSupported/
ServiceModelDeprecated/
InvalidResourceProperties
Model not supported or deprecated in selected region
  • The updated model may not be supported in the selected region. Please verify its availability in the Azure AI Foundry models document
FlagMustBeSetForRestore/
NameUnavailable/
CustomDomainInUse
Soft-deleted resource requires restore flag or purge This error occurs when you try to deploy a Cognitive Services resource that was soft-deleted earlier. Azure requires you to explicitly set the restore flag to true if you want to recover the soft-deleted resource. If you don't want to restore the resource, you must purge the deleted resource first before redeploying.

Example causes:
  • Trying to redeploy a Cognitive Services account with the same name as a previously deleted one
  • The deleted resource still exists in a soft-delete retention state

How to fix:
  • If you want to restore → add "restore": true in your template properties
  • If you want a fresh deployment → purge the resource using:
    az cognitiveservices account purge --name <resource-name> --resource-group <resource-group> --location <location>
  • For more details, refer to Soft delete and resource restore
ContainerAppOperationError Container image build or deployment issue
LinkedAuthorizationFailed Service principal lacks permission to use a linked resource required for deployment This error occurs when a service principal doesn't have permission to perform an action on a linked resource that is required for the operation (e.g., cluster creation).

Common causes:
  • The service principal has permission on the primary resource but lacks permission on the linked scope
  • Missing role assignment for operations like Microsoft.Network/ddosProtectionPlans/join/action

Resolution:
ContainerOperationFailure Container image or storage resource does not exist This error occurs when an operation fails because the specified container resource does not exist. This can happen with Azure Container Registry images or Azure Storage blob containers.

Example error message:
ContainerOperationFailure: The specified resource does not exist. RequestId:xxxxx Time:xxxxx

Common causes:
  • Invalid container image tag: The specified image tag does not exist in the container registry
  • Non-existent container registry: The container registry endpoint is incorrect or inaccessible
  • Missing blob container: The storage blob container referenced by the application does not exist
  • Incorrect storage account URL: The storage account endpoint is misconfigured
  • Permission issues: The managed identity lacks permissions to access the container registry or storage account

Resolution:
  • Verify container image exists:
    az acr repository show-tags --name <registry-name> --repository <image-name>
  • Check image tag in deployment: Ensure the imageTag parameter matches an existing tag in the registry
  • Verify storage containers exist:
    az storage container list --account-name <storage-account-name> --auth-mode login
  • Check role assignments: Ensure the Container App's managed identity has AcrPull role on the container registry and Storage Blob Data Contributor role on the storage account
  • Rebuild and push container images: If images are missing, follow the ACR Build & Push Guide
  • Verify storage account URL: Ensure APP_STORAGE_BLOB_URL and APP_STORAGE_QUEUE_URL in App Configuration point to the correct storage account

Reference:

💡 Note: If you encounter any other issues, you can refer to the Common Deployment Errors documentation. If the problem persists, you can also raise an bug in our MACAE Github Issues for further support.