Skip to content

Commit f71b3a3

Browse files
NirajC-MicrosoftNirajC-Microsoft
committed
Add Description for error
1 parent 47f80ba commit f71b3a3

1 file changed

Lines changed: 18 additions & 18 deletions

File tree

‎docs/TroubleShootingSteps.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -10,38 +10,38 @@ Use these as quick reference guides to unblock your deployments.
1010

1111
| Issue/Error Code | Description | Steps to Resolve |
1212
|-----------|-------------|------------------|
13-
| **ReadOnlyDisabledSubscription** | | - Check if you have an active subscription before starting the deployment<br>- Depending on the type of the Azure Subscription, the expiration date might have been reached<br>- You have to activate the Azure Subscription before creating any Azure resource<br>- Refer to [Reactivate a disabled Azure subscription](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/subscription-disabled) documentation |
14-
| **MissingSubscriptionRegistration/AllowBringYourOwnPublicIpAddress** | | **Enable `AllowBringYourOwnPublicIpAddress` Feature**<br><br>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.<br><br>**Steps:**<br>1. Run the following command to register the feature:<br>`az feature register --namespace Microsoft.Network --name AllowBringYourOwnPublicIpAddress`<br><br>2. Wait for the registration to complete. Check the status using:<br>`az feature show --namespace Microsoft.Network --name AllowBringYourOwnPublicIpAddress --query properties.state`<br><br>3. The output should show: "Registered"<br><br>4. Once the feature is registered, refresh the provider:<br>`az provider register --namespace Microsoft.Network`<br><br>💡 Note: Feature registration may take several minutes to complete. This needs to be done only once per Azure subscription. |
15-
| **Unauthorized - Operation cannot be completed without additional quota** | | - Check your quota usage using:<br>`az vm list-usage --location "<Location>" -o table`<br>- To request more quota refer to [VM Quota Request](https://techcommunity.microsoft.com/blog/startupsatmicrosoftblog/how-to-increase-quota-for-specific-types-of-azure-virtual-machines/3792394) |
16-
| **CrossTenantDeploymentNotPermitted** | | - **Check tenant match:** Ensure your deployment identity (user/SP) and the target resource group are in the same tenant:<br>`az account show`<br>`az group show --name <RG_NAME>`<br>- **Verify pipeline/service principal:** If using CI/CD, confirm the service principal belongs to the same tenant and has permissions on the resource group<br>- **Avoid cross-tenant references:** Make sure your Bicep doesn't reference subscriptions, resource groups, or resources in another tenant<br>- **Test minimal deployment:** Deploy a simple resource to the same resource group to confirm identity and tenant are correct<br>- **Guest/external accounts:** Avoid using guest users from other tenants; use native accounts or SPs in the tenant |
17-
| **RequestDisallowedByPolicy** | | - This typically indicates that an Azure Policy is preventing the requested action due to policy restrictions in your subscription<br>- For more details and guidance on resolving this issue, refer to: [RequestDisallowedByPolicy](https://learn.microsoft.com/en-us/troubleshoot/azure/azure-kubernetes/create-upgrade-delete/error-code-requestdisallowedbypolicy) |
18-
| **SpecialFeatureOrQuotaIdRequired** | | This error occurs when your subscription does not have access to certain Azure OpenAI models.<br><br>**Example error message:**<br>`SpecialFeatureOrQuotaIdRequired: The current subscription does not have access to this model 'Format:OpenAI,Name:o3,Version:2025-04-16'.`<br><br>**Resolution:**<br>To gain access, submit a request using the official form:<br>👉 [Azure OpenAI Model Access Request](https://customervoice.microsoft.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR7en2Ais5pxKtso_Pz4b1_xUQ1VGQUEzRlBIMVU2UFlHSFpSNkpOR0paRSQlQCN0PWcu)<br><br>You'll need to use this form if you require access to the following restricted models:<br>- gpt-5<br>- o3<br>- o3-pro<br>- deep research<br>- reasoning summary<br>- gpt-image-1<br><br>Once your request is approved, redeploy your resource. |
19-
| **ResourceProviderError** | | - This error occurs when the resource provider is not registered in your subscription<br>- To register it, refer to [Register Resource Provider](https://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/error-register-resource-provider?tabs=azure-cli) documentation |
13+
| **ReadOnlyDisabledSubscription** | Subscription is disabled or in read-only state | - Check if you have an active subscription before starting the deployment<br>- Depending on the type of the Azure Subscription, the expiration date might have been reached<br>- You have to activate the Azure Subscription before creating any Azure resource<br>- Refer to [Reactivate a disabled Azure subscription](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/subscription-disabled) documentation |
14+
| **MissingSubscriptionRegistration/AllowBringYourOwnPublicIpAddress** | Required feature not registered in subscription | **Enable `AllowBringYourOwnPublicIpAddress` Feature**<br><br>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.<br><br>**Steps:**<br>1. Run the following command to register the feature:<br>`az feature register --namespace Microsoft.Network --name AllowBringYourOwnPublicIpAddress`<br><br>2. Wait for the registration to complete. Check the status using:<br>`az feature show --namespace Microsoft.Network --name AllowBringYourOwnPublicIpAddress --query properties.state`<br><br>3. The output should show: "Registered"<br><br>4. Once the feature is registered, refresh the provider:<br>`az provider register --namespace Microsoft.Network`<br><br>💡 Note: Feature registration may take several minutes to complete. This needs to be done only once per Azure subscription. |
15+
| **Unauthorized - Operation cannot be completed without additional quota** | Insufficient quota for requested operation | - Check your quota usage using:<br>`az vm list-usage --location "<Location>" -o table`<br>- To request more quota refer to [VM Quota Request](https://techcommunity.microsoft.com/blog/startupsatmicrosoftblog/how-to-increase-quota-for-specific-types-of-azure-virtual-machines/3792394) |
16+
| **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:<br>`az account show`<br>`az group show --name <RG_NAME>`<br>- **Verify pipeline/service principal:** If using CI/CD, confirm the service principal belongs to the same tenant and has permissions on the resource group<br>- **Avoid cross-tenant references:** Make sure your Bicep doesn't reference subscriptions, resource groups, or resources in another tenant<br>- **Test minimal deployment:** Deploy a simple resource to the same resource group to confirm identity and tenant are correct<br>- **Guest/external accounts:** Avoid using guest users from other tenants; use native accounts or SPs in the tenant |
17+
| **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<br>- For more details and guidance on resolving this issue, refer to: [RequestDisallowedByPolicy](https://learn.microsoft.com/en-us/troubleshoot/azure/azure-kubernetes/create-upgrade-delete/error-code-requestdisallowedbypolicy) |
18+
| **SpecialFeatureOrQuotaIdRequired** | Subscription lacks access to specific Azure OpenAI models | This error occurs when your subscription does not have access to certain Azure OpenAI models.<br><br>**Example error message:**<br>`SpecialFeatureOrQuotaIdRequired: The current subscription does not have access to this model 'Format:OpenAI,Name:o3,Version:2025-04-16'.`<br><br>**Resolution:**<br>To gain access, submit a request using the official form:<br>👉 [Azure OpenAI Model Access Request](https://customervoice.microsoft.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR7en2Ais5pxKtso_Pz4b1_xUQ1VGQUEzRlBIMVU2UFlHSFpSNkpOR0paRSQlQCN0PWcu)<br><br>You'll need to use this form if you require access to the following restricted models:<br>- gpt-5<br>- o3<br>- o3-pro<br>- deep research<br>- reasoning summary<br>- gpt-image-1<br><br>Once your request is approved, redeploy your resource. |
19+
| **ResourceProviderError** | Resource provider not registered in subscription | - This error occurs when the resource provider is not registered in your subscription<br>- To register it, refer to [Register Resource Provider](https://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/error-register-resource-provider?tabs=azure-cli) documentation |
2020

2121
--------------------------------
2222

2323
### Quota & Capacity Limitations
2424

2525
| Issue/Error Code | Description | Steps to Resolve |
2626
|-----------------|-------------|------------------|
27-
| **InternalSubscriptionIsOverQuotaForSku/ManagedEnvironmentProvisioningError** | | 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.<br><br>For PowerShell, use the `Get-AzVMUsage` cmdlet to find virtual machine quotas:<br>`Get-AzVMUsage -Location "West US"`<br><br>Based on available quota you can deploy application otherwise, you can request for more quota |
28-
| **InsufficientQuota** | | - Check if you have sufficient quota available in your subscription before deployment<br>- To verify, refer to the [quota_check](../docs/quota_check.md) file for details |
29-
| **MaxNumberOfRegionalEnvironmentsInSubExceeded** | | - This error occurs when you try to create more than the allowed number of **Azure Container App Environments (ACA Environments)** in the same region for a subscription<br>- For example, in **Sweden Central**, only **1 Container App Environment** is allowed per subscription<br>- The subscription 'xxxx-xxxx' cannot have more than 1 Container App Environments in Sweden Central<br><br>**To fix this, you can:**<br>- Deploy the Container App Environment in a **different region**, OR<br>- Request a quota increase via Azure Support → [Quota Increase Request](https://go.microsoft.com/fwlink/?linkid=2208872) |
30-
| **SkuNotAvailable** | | - You receive this error in the following scenarios:<br> - When the resource SKU you've selected, such as VM size, isn't available for a location or zone<br> - If you're deploying an Azure Spot VM or Spot scale set instance, and there isn't any capacity for Azure Spot in this location. For more information, see Spot error messages |
27+
| **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.<br><br>For PowerShell, use the `Get-AzVMUsage` cmdlet to find virtual machine quotas:<br>`Get-AzVMUsage -Location "West US"`<br><br>Based on available quota you can deploy application otherwise, you can request for more quota |
28+
| **InsufficientQuota** | Not enough quota available in subscription | - Check if you have sufficient quota available in your subscription before deployment<br>- To verify, refer to the [quota_check](../docs/quota_check.md) file for details |
29+
| **MaxNumberOfRegionalEnvironmentsInSubExceeded** | Maximum Container App Environments limit reached for region | - This error occurs when you try to create more than the allowed number of **Azure Container App Environments (ACA Environments)** in the same region for a subscription<br>- For example, in **Sweden Central**, only **1 Container App Environment** is allowed per subscription<br>- The subscription 'xxxx-xxxx' cannot have more than 1 Container App Environments in Sweden Central<br><br>**To fix this, you can:**<br>- Deploy the Container App Environment in a **different region**, OR<br>- Request a quota increase via Azure Support → [Quota Increase Request](https://go.microsoft.com/fwlink/?linkid=2208872) |
30+
| **SkuNotAvailable** | Requested SKU not available in selected location or zone | - You receive this error in the following scenarios:<br> - When the resource SKU you've selected, such as VM size, isn't available for a location or zone<br> - If you're deploying an Azure Spot VM or Spot scale set instance, and there isn't any capacity for Azure Spot in this location. For more information, see Spot error messages |
3131

3232
--------------------------------
3333

3434
### Resource Group & Deployment Management
3535

3636
| Issue/Error Code | Description | Steps to Resolve |
3737
|-----------------|-------------|------------------|
38-
| **ResourceGroupNotFound** | | **Option 1:**<br>1. Go to [Azure Portal](https:/portal.azure.com/#home)<br>2. Click on **"Resource groups"** option<br>![alt text](../docs/images/AzureHomePage.png)<br>3. Search for the resource group in the search bar. If it exists, you can proceed<br>![alt text](../docs/images/resourcegroup1.png)<br><br>**Option 2:**<br>- This error can occur if you deploy using the same .env file from a previous deployment<br>- Create a new environment before redeploying:<br>`azd env new <env-name>` |
39-
| **ResourceGroupBeingDeleted** | | **Steps:**<br>1. Go to [Azure Portal](https://portal.azure.com/#home)<br>2. Go to resource group option and search for targeted resource group<br>3. If the resource group is being deleted, you cannot use it. Create a new one or use a different resource group |
40-
| **DeploymentActive** | | - This occurs when a deployment is already in progress and another deployment is triggered in the same resource group<br>- Cancel the ongoing deployment before starting a new one<br>- Do not initiate a new deployment until the previous one is completed |
41-
| **DeploymentCanceled** | | 1. **Check deployment history:**<br> - Go to Azure Portal → Resource Group → Deployments<br> - Review the detailed error message<br>2. **Identify the root cause:**<br> - Dependent resource failed to deploy<br> - Validation error occurred<br> - Manual cancellation was triggered<br>3. **Validate template:**<br> `az deployment group validate --resource-group <rg-name> --template-file main.bicep`<br>4. **Check resource limits/quotas**<br>5. **Fix the failed dependency**<br>6. **Retry deployment:**<br> `az deployment group create --resource-group <rg-name> --template-file main.bicep`<br><br>💡 **Note:** DeploymentCanceled is a wrapper error — check inner errors in deployment logs |
42-
| **DeploymentCanceled(user.canceled)** | | - Deployment was manually canceled by the user (Portal, CLI, or pipeline)<br>- Check deployment history and logs to confirm who/when it was canceled<br>- If accidental, retry the deployment<br>- For pipelines, ensure no automation or timeout is triggering cancellation<br>- Use deployment locks or retry logic to prevent accidental cancellations |
43-
| **DeploymentNotFound** | | - 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<br>- Do not change the location when redeploying a deleted RG, OR<br>- Use new names for the RG and environment during redeployment |
44-
| **ResourceGroupDeletionTimeout** | | - Some resources may be stuck deleting or have dependencies; check RG resources and status<br>- Ensure no resource locks or Azure Policies are blocking deletion<br>- Retry deletion via CLI/PowerShell:<br> `az group delete --name <RG_NAME> --yes --no-wait`<br>- Check Activity Log to identify failing resources<br>- Escalate to Azure Support if deletion is stuck |
38+
| **ResourceGroupNotFound** | Specified resource group does not exist | **Option 1:**<br>1. Go to [Azure Portal](https:/portal.azure.com/#home)<br>2. Click on **"Resource groups"** option<br>![alt text](../docs/images/AzureHomePage.png)<br>3. Search for the resource group in the search bar. If it exists, you can proceed<br>![alt text](../docs/images/resourcegroup1.png)<br><br>**Option 2:**<br>- This error can occur if you deploy using the same .env file from a previous deployment<br>- Create a new environment before redeploying:<br>`azd env new <env-name>` |
39+
| **ResourceGroupBeingDeleted** | Resource group is currently being deleted | **Steps:**<br>1. Go to [Azure Portal](https://portal.azure.com/#home)<br>2. Go to resource group option and search for targeted resource group<br>3. If the resource group is being deleted, you cannot use it. Create a new one or use a different resource group |
40+
| **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<br>- Cancel the ongoing deployment before starting a new one<br>- Do not initiate a new deployment until the previous one is completed |
41+
| **DeploymentCanceled** | Deployment was canceled before completion | 1. **Check deployment history:**<br> - Go to Azure Portal → Resource Group → Deployments<br> - Review the detailed error message<br>2. **Identify the root cause:**<br> - Dependent resource failed to deploy<br> - Validation error occurred<br> - Manual cancellation was triggered<br>3. **Validate template:**<br> `az deployment group validate --resource-group <rg-name> --template-file main.bicep`<br>4. **Check resource limits/quotas**<br>5. **Fix the failed dependency**<br>6. **Retry deployment:**<br> `az deployment group create --resource-group <rg-name> --template-file main.bicep`<br><br>💡 **Note:** DeploymentCanceled is a wrapper error — check inner errors in deployment logs |
42+
| **DeploymentCanceled(user.canceled)** | User manually canceled the deployment | - Deployment was manually canceled by the user (Portal, CLI, or pipeline)<br>- Check deployment history and logs to confirm who/when it was canceled<br>- If accidental, retry the deployment<br>- For pipelines, ensure no automation or timeout is triggering cancellation<br>- Use deployment locks or retry logic to prevent accidental cancellations |
43+
| **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<br>- Do not change the location when redeploying a deleted RG, OR<br>- Use new names for the RG and environment during redeployment |
44+
| **ResourceGroupDeletionTimeout** | Resource group deletion exceeded timeout limit | - Some resources may be stuck deleting or have dependencies; check RG resources and status<br>- Ensure no resource locks or Azure Policies are blocking deletion<br>- Retry deletion via CLI/PowerShell:<br> `az group delete --name <RG_NAME> --yes --no-wait`<br>- Check Activity Log to identify failing resources<br>- Escalate to Azure Support if deletion is stuck |
4545

4646
--------------------------------
4747

0 commit comments

Comments
 (0)