Skip to content

Commit 1273265

Browse files
NirajC-MicrosoftNirajC-Microsoft
committed
Additional troubleshooting steps
1 parent 952ac52 commit 1273265

File tree

1 file changed

+173
-2
lines changed

1 file changed

+173
-2
lines changed

‎docs/TroubleShootingSteps.md‎

Lines changed: 173 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,13 +103,13 @@ based on available quota you can deploy application otherwise, you can request f
103103
</details>
104104

105105
<details>
106-
<summary><b>DeploymentModelNotSupported</b></summary>
106+
<summary><b>DeploymentModelNotSupported/ ServiceModelDeprecated/ InvalidResourceProperties</b></summary>
107107

108108
- The updated model may not be supported in the selected region. Please verify its availability in the [Azure AI Foundry models](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/models?tabs=global-standard%2Cstandard-chat-completions) document.
109109

110110
</details>
111111
<details>
112-
<summary><b>LinkedInvalidPropertyId/ ResourceNotFound/DeploymentOutputEvaluationFailed/ CanNotRestoreANonExistingResource </b></summary>
112+
<summary><b>LinkedInvalidPropertyId/ ResourceNotFound/DeploymentOutputEvaluationFailed/ CanNotRestoreANonExistingResource / The language expression property array index is out of bounds</b></summary>
113113

114114
- Before using any resource ID, ensure it follows the correct format.
115115
- Verify that the resource ID you are passing actually exists.
@@ -128,6 +128,8 @@ based on available quota you can deploy application otherwise, you can request f
128128
```
129129
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{name}
130130
```
131+
- 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 ID's.
132+
131133
- For more information refer [Resource Not Found errors solutions](https://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/error-not-found?tabs=bicep)
132134
133135
</details>
@@ -297,5 +299,174 @@ The subscription 'xxxx-xxxx' cannot have more than 1 Container App Environments
297299
298300
</details>
299301
302+
<details>
303+
<summary><b>Unauthorized - Operation cannot be completed without additional quota</b> </summary>
304+
305+
- You can check your quota usage using `az vm list-usage`.
306+
307+
```
308+
az vm list-usage --location "<Location>" -o table
309+
```
310+
- To Request more quota refer [VM Quota Request](https://techcommunity.microsoft.com/blog/startupsatmicrosoftblog/how-to-increase-quota-for-specific-types-of-azure-virtual-machines/3792394).
311+
312+
</details>
313+
314+
<details><summary><b>ParentResourceNotfound</b>
315+
</summary>
316+
317+
- You can refer to the [Parent Resource Not found](https://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/error-parent-resource?tabs=bicep) documentation if you encounter this error.
318+
319+
</details>
320+
321+
<details><summary><b>ResourceProviderError</b></summary>
322+
323+
- This error occurs when the resource provider is not registered in your subscription.
324+
- To register it, refer to [Register Resource Provider](https://learn.microsoft.com/en-us/azure/role-based-access-control/troubleshooting?tabs=bicep#:~:text=Copy-,PrincipalNotFound,-Principal%20%7BprincipalId%7D%20does) documentation.
325+
326+
</details>
327+
328+
<details><summary><b>Conflict - Cannot use the SKU Basic with File Change Audit for site.</b></summary>
329+
330+
- This error happens because File Change Audit logs aren’t supported on Basic SKU App Service Plans.
331+
332+
- Upgrading to Premium/Isolated SKU (supports File Change Audit), or
333+
334+
- Disabling File Change Audit in Diagnostic Settings if you must stay on Basic.
335+
- Always cross-check the [supported log types](https://aka.ms/supported-log-types)
336+
before adding diagnostic logs to your Bicep templates.
337+
338+
</details>
339+
340+
<details>
341+
342+
<summary><b>AccountPropertyCannotBeUpdated</b></summary>
343+
344+
- The property **`isHnsEnabled`** (Hierarchical Namespace for Data Lake Gen2) is **read-only** and can only be set during **storage account creation**.
345+
- Once a storage account is created, this property **cannot be updated**.
346+
- Trying to update it via ARM template, Bicep, CLI, or Portal will fail.
347+
348+
- **Resolution**
349+
- Create a **new storage account** with `isHnsEnabled=true` if you require hierarchical namespace.
350+
- Migration may be needed if you already have data.
351+
- Refer to [Storage Account Update Restrictions](https://aka.ms/storageaccountupdate) for more details.
352+
353+
</details>
354+
355+
<details><summary><b>InvalidRequestContent</b></summary>
356+
357+
- The deployment values either include values that aren't recognized, or required values are missing. Confirm the values for your resource type.
358+
- You can refer [Invalid Request Content error](https://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/common-deployment-errors#:~:text=InvalidRequestContent,Template%20reference) documentation.
359+
360+
</details>
361+
362+
<details><summary><b>ReadOnlyDisabledSubscription</b></summary>
363+
364+
- Depending on the type of the Azure Subscription it might be an expiration date is reached.
365+
366+
- You have to activate the Azure Subscription before creating any Azure resource.
367+
- You can refer [Reactivate a disabled Azure subscription](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/subscription-disabled) Documentation.
368+
369+
</details>
370+
371+
372+
<details><summary><b>SkuNotAvailable</b></summary>
373+
374+
- You receive this error in the following scenarios:
375+
- When the resource SKU you've selected, such as VM size, isn't available for a location or zone.
376+
- 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.
377+
</details>
378+
379+
<details><summary><b>CrossTenantDeploymentNotPermitted</b></summary>
380+
381+
- Check tenant match: Ensure your deployment identity (user/SP) and the target resource group are in the same tenant.
382+
```
383+
az account show
384+
az group show --name <RG_NAME>
385+
```
386+
387+
- Verify pipeline/service principal: If using CI/CD, confirm the service principal belongs to the same tenant and has permissions on the resource group.
388+
389+
- Avoid cross-tenant references: Make sure your Bicep doesn’t reference subscriptions, resource groups, or resources in another tenant.
390+
391+
- Test minimal deployment: Deploy a simple resource to the same resource group to confirm identity and tenant are correct.
392+
393+
- Guest/external accounts: Avoid using guest users from other tenants; use native accounts or SPs in the tenant.
394+
395+
</details>
396+
397+
<details><summary><b>RequestDisallowedByPolicy </b></summary>
398+
399+
- This typically indicates that an Azure Policy is preventing the requested action due to policy restrictions in your subscription.
400+
401+
- For more details and guidance on resolving this issue, please refer to the official Microsoft documentation: [RequestDisallowedByPolicy](https://learn.microsoft.com/en-us/troubleshoot/azure/azure-kubernetes/create-upgrade-delete/error-code-requestdisallowedbypolicy)
402+
403+
</details>
404+
405+
<details>
406+
<summary><b>FlagMustBeSetForRestore/NameUnavailable/CustomDomainInUse</b></summary>
407+
408+
- This error occurs when you try to deploy a Cognitive Services resource that was **soft-deleted** earlier.
409+
- Azure requires you to explicitly set the **`restore` flag** to `true` if you want to recover the soft-deleted resource.
410+
- If you don’t want to restore the resource, you must **purge the deleted resource** first before redeploying.
411+
Example causes:
412+
- Trying to redeploy a Cognitive Services account with the same name as a previously deleted one.
413+
- The deleted resource still exists in a **soft-delete retention state**.
414+
**How to fix:**
415+
1. If you want to restore → add `"restore": true` in your template properties.
416+
2. If you want a fresh deployment → purge the resource using:
417+
```bash
418+
az cognitiveservices account purge \
419+
--name <resource-name> \
420+
--resource-group <resource-group> \
421+
--location <location>
422+
```
423+
For more details, refer to [Soft delete and resource restore](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/delete-resource-group?tabs=azure-powershell)
424+
.
425+
</details>
426+
427+
<details>
428+
<summary><b>PrincipalNotFound</b></summary>
429+
430+
- 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.
431+
- It can also happen due to **replication delays** right after creating a new principal.
432+
**Example causes:**
433+
- The specified **Object ID** is invalid or belongs to another tenant.
434+
- The principal was recently created but Azure AD has not yet replicated it.
435+
- Attempting to assign a role to a non-existing or deleted Service Principal/User/Group.
436+
**How to fix:**
437+
1. Verify that the **principal ID is correct** and exists in the same directory/tenant.
438+
```bash
439+
az ad sp show --id <object-id>
440+
```
441+
2. If the principal was just created, wait a few minutes and retry.
442+
3. Explicitly set the principalType property (ServicePrincipal, User, or Group) in your ARM/Bicep template to avoid replication delays.
443+
4. If the principal does not exist, create it again before assigning roles.
444+
For more details, see [Azure PrincipalType documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/troubleshooting?tabs=bicep)
445+
</details>
446+
<details>
447+
<summary><b>RedundancyConfigurationNotAvailableInRegion</b></summary>
448+
449+
- 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**.
450+
- Example: Creating a storage account with **GRS** in **italynorth** will fail with this error.
451+
```bash
452+
az storage account create -n mystorageacct123 -g myResourceGroup -l italynorth --sku Standard_GRS --kind StorageV2
453+
```
454+
- To check supported SKUs for your region:
455+
```bash
456+
az storage account list-skus -l italynorth -o table
457+
```
458+
Use a supported redundancy option (e.g., Standard_LRS) in the same region
459+
Or deploy the Storage Account in a region that supports your chosen redundancy.
460+
For more details, refer to [Azure Storage redundancy documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-redundancy?utm_source=chatgpt.com).
461+
</details>
462+
463+
<details> <summary><b>DeploymentNotFound</b></summary>
464+
465+
<br> This issue occurs when the user deletes a previous deployment along with the resource group (RG), and then redeploys the same RG with the same environment name but in a different location.
466+
467+
To avoid the DeploymentNotFound error, Do not change the location when redeploying a deleted RG, or Use new names for the RG and environment during redeployment.
468+
</details>
469+
470+
300471
💡 Note: If you encounter any other issues, you can refer to the [Common Deployment Errors](https://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/common-deployment-errors) documentation.
301472
If the problem persists, you can also raise an bug in our [MACAE Github Issues](https://github.com/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator/issues) for further support.

0 commit comments

Comments
 (0)