Merge pull request #7001 from deeikele/upgrade-path-updates

added common issues to docs

Author: prmerger-automator[bot]

articles/ai-foundry/how-to/upgrade-azure-openai.md

@@ -56,7 +56,7 @@ The upgrade converts your Azure OpenAI resource type to Azure AI Foundry resourc
 
 ## How to upgrade
 
-As a prerequisite to upgrade, managed identity must be enabled on your Azure OpenAI resource. Upgrade can be completed via the Azure AI Foundry portal or using Azure Bicep or Resource Manager templates.
+As a prerequisite to upgrade, managed identity must be enabled on your Azure OpenAI resource. Upgrade can be completed via the Azure AI Foundry portal, or using Azure Bicep or Resource Manager templates (recommended for resource configurations with custom security settings such as private networking).
 
 # [Foundry portal](#tab/portal)
 
@@ -183,6 +183,19 @@ To rollback, convert your template configuration back to 'OpenAI' as kind.
 
 ---
 
+## Troubleshooting Common Issues
+
+Azure resource limits and organizational configurations may require additional steps to complete the upgrade. The table below outlines some of the most common issues along with recommended solutions to help troubleshooting.
+
+|Issue|Solution/mitigation|
+|---|---|
+|User principal lacks account/write permissions|Obtain a privileged Azure RBAC role to manage top-level Azure resources e.g. Owner, Contributor, Azure AI Administrator.| 
+|Managed identity is not enabled on the Azure OpenAI resource|Configure managed identity on your resource via templates or Azure portal.|
+|No permissions to create agents, while you are the owner/contributor on the resource.|An EntraID data plane role is required for development actions including agents. Examples include Azure AI User or Azure AI Project Manager role. Owner and Contributor roles only grant access to management operations in Azure such as managing deployments.|
+|An Azure Policy conflict occurred.|Your organization may have put constraints on resource configurations. Inspect the details of the policy violation error. Then upgrade your resource via template options for further customization. For example, network configurations for Agents can only be configured via template options such as Azure Bicep.|
+|Exceeded number of Azure OpenAI instances of 30 per subscription per region when rolling back.|Delete an Azure OpenAI resource or upgrade it to the Azure AI Foundry. Then retry rolling back your current resource.|
+|Exceeded number of AIServices instances of 100 per subscription per region.|Delete an Azure AI Foundry resource you may not use in this subscription. Then retry upgrading your current resource.|
+
 ## How to inspect whether a resource has been upgraded
 
 The following Azure resource property is available to inspect whether a resource was previously upgraded to AI Foundry.