|
| 1 | +--- |
| 2 | +title: Troubleshoot virtual network issues |
| 3 | +description: Learn how to troubleshoot common scenarios for virtual networks in Microsoft Power Platform. |
| 4 | +author: faix |
| 5 | +ms.component: pa-admin |
| 6 | +ms.topic: troubleshooting-general |
| 7 | +ms.date: 09/15/2025 |
| 8 | +ms.author: osfaixat |
| 9 | +ms.reviewer: sericks |
| 10 | +search.audienceType: |
| 11 | + - admin |
| 12 | +contributors: |
| 13 | +ms.custom: sap:Environment - Administration |
| 14 | + |
| 15 | +#customer intent: As a developer or IT administrator, I want to troubleshoot my virtual network configuration in Power Platform so that my applications work as intended. |
| 16 | +--- |
| 17 | + |
| 18 | +# Troubleshoot virtual network issues |
| 19 | + |
| 20 | +This article provides guidance to troubleshoot common scenarios for [virtual networks](/power-platform/admin/vnet-support-overview) in Microsoft Power Platform. This article focuses on the use of the [Microsoft.PowerPlatform.EnterprisePolicies](https://www.powershellgallery.com/packages/Microsoft.PowerPlatform.EnterprisePolicies) PowerShell module to help you identify and resolve issues that are related to virtual network configurations. |
| 21 | + |
| 22 | +## Use the diagnostics PowerShell module |
| 23 | + |
| 24 | +The `Microsoft.PowerPlatform.EnterprisePolicies` PowerShell module is designed to help you diagnose and troubleshoot issues that are related to virtual network configurations in Power Platform. You can use the tool to check the connectivity between your Power Platform environment and your virtual network. You can also use it to identify any misconfigurations that might be causing issues. This diagnostics PowerShell module is available from the PowerShell Gallery and its GitHub repository: [PowerPlatform-EnterprisePolicies](https://github.com/microsoft/PowerPlatform-EnterprisePolicies). |
| 25 | + |
| 26 | +### Install the module |
| 27 | + |
| 28 | +To install the diagnostics PowerShell module, run the following PowerShell command: |
| 29 | + |
| 30 | +```powershell |
| 31 | +Install-Module -Name Microsoft.PowerPlatform.EnterprisePolicies |
| 32 | +``` |
| 33 | + |
| 34 | +### Run the diagnostic functions included in the module |
| 35 | + |
| 36 | +After the module is installed, import it into your PowerShell session by running the following command: |
| 37 | + |
| 38 | +```powershell |
| 39 | +Import-Module Microsoft.PowerPlatform.EnterprisePolicies |
| 40 | +``` |
| 41 | + |
| 42 | +The module includes several functions to diagnose and troubleshoot issues that are related to virtual network configurations. Some of the key functions are as follows: |
| 43 | + |
| 44 | +- [Get-EnvironmentRegion](https://github.com/microsoft/PowerPlatform-EnterprisePolicies/blob/main/docs/en-US/Microsoft.PowerPlatform.EnterprisePolicies/Get-EnvironmentRegion.md): Retrieves the region of the specified Power Platform environment |
| 45 | +- [Get-EnvironmentUsage](https://github.com/microsoft/PowerPlatform-EnterprisePolicies/blob/main/docs/en-US/Microsoft.PowerPlatform.EnterprisePolicies/Get-EnvironmentUsage.md): Provides information about the usage of the specified Power Platform environment |
| 46 | +- [Test-DnsResolution](https://github.com/microsoft/PowerPlatform-EnterprisePolicies/blob/main/docs/en-US/Microsoft.PowerPlatform.EnterprisePolicies/Test-DnsResolution.md): Tests the DNS resolution for the specified domain name |
| 47 | +- [Test-NetworkConnectivity](https://github.com/microsoft/PowerPlatform-EnterprisePolicies/blob/main/docs/en-US/Microsoft.PowerPlatform.EnterprisePolicies/Test-NetworkConnectivity.md): Tests the network connectivity between the Power Platform environment and the specified virtual network |
| 48 | + |
| 49 | +### Report issues in the diagnostics module |
| 50 | + |
| 51 | +If you encounter issues when you run the diagnostics module, report them through the GitHub repository where the module is hosted. The repository is available at: [PowerPlatform-EnterprisePolicies](https://github.com/microsoft/PowerPlatform-EnterprisePolicies). |
| 52 | + |
| 53 | +To report an issue, go to the **Issues** section of the repository, and [open a new issue](https://github.com/microsoft/PowerPlatform-EnterprisePolicies/issues/new). Provide detailed information about the issue that you experience, including any error messages or log entries that might help when investigating the issue. Don't include any sensitive information in your report. |
| 54 | + |
| 55 | +## Troubleshoot common issues |
| 56 | + |
| 57 | +### Misconfiguration of regions |
| 58 | + |
| 59 | +If everything is correctly configured but you still experience issues, use the `Get-EnvironmentRegion` function from the diagnostics PowerShell module to check whether the regions of your Power Platform environment are the same as the regions of your virtual network. Run the following command: |
| 60 | + |
| 61 | +```powershell |
| 62 | +Get-EnvironmentRegion -EnvironmentId "<EnvironmentId>" |
| 63 | +``` |
| 64 | + |
| 65 | +Your environment belongs to a specific PowerPlatform region. However, a PowerPlatform region can span two Azure regions. You have to make sure that your virtual network is configured in both the Azure regions that correspond to your PowerPlatform region. Your environment can be located in either of the two Azure regions, and it can also automatically fail over between them. Therefore, to ensure high availability and connectivity, you should configure your virtual network in both Azure regions that are associated with your PowerPlatform region. To learn how PowerPlatform regions map to Azure regions that support the virtual network functionality, see [Power Platform regions](/power-platform/admin/vnet-support-overview#supported-regions). |
| 66 | + |
| 67 | +### Hostname not found |
| 68 | + |
| 69 | +If you experience issues that affect hostname resolution, use the `Test-DnsResolution` function from the diagnostics PowerShell module to check whether the hostname is resolved correctly. Run the following command: |
| 70 | + |
| 71 | +```powershell |
| 72 | +Test-DnsResolution -EnvironmentId "<EnvironmentId>" -HostName "<HostName>" |
| 73 | +``` |
| 74 | + |
| 75 | +This command tests the DNS resolution for the specified hostname in the context of your Power Platform environment. The request initiates from your delegated subnet and tries to resolve the hostname by using the DNS server configured for your virtual network. If the hostname isn't resolved correctly, you might have to check your DNS settings to make sure that the hostname is configured correctly. |
| 76 | + |
| 77 | +> [!IMPORTANT] |
| 78 | +> If you notice that your DNS setup is incorrect, and you have to update the DNS server settings for your virtual network, see [Can I update the DNS address of my virtual network after it's delegated to "Microsoft.PowerPlatform/enterprisePolicies"?](/power-platform/admin/vnet-support-overview#can-i-update-the-dns-address-of-my-virtual-network-after-its-delegated-to-microsoftpowerplatformenterprisepolicies) |
| 79 | +
|
| 80 | +### Can't connect to the resource |
| 81 | + |
| 82 | +If you experience issues that affect connectivity to a resource, use the `Test-NetworkConnectivity` function from the diagnostics PowerShell module to check for connectivity. Run the following command: |
| 83 | + |
| 84 | +```powershell |
| 85 | +Test-NetworkConnectivity -EnvironmentId "<EnvironmentId>" -Destination "<ResourceAddress>" -Port 1433 |
| 86 | +``` |
| 87 | + |
| 88 | +This command tries to establish a TCP connection to the specified destination and port in the context of your Power Platform environment. The request initiates from your delegated subnet and tries to connect to the specified destination by using the network configuration from your virtual network. If the connection fails, you might have to check your network settings to make sure that the destination is reachable from your virtual network. If the connection is successful, it indicates that network connectivity exists between the Power Platform environment and the specified resource. |
| 89 | + |
| 90 | +> [!NOTE] |
| 91 | +> This command tests only whether a TCP connection can be established to the specified destination and port. It doesn't test whether the resource is available or whether any application-level issues might be preventing access to the resource. |
| 92 | +> Some firewalls might allow TCP connections to be established, but they then block actual traffic to the resource (for example, HTTPS). Therefore, even if the command indicates network connectivity, that status doesn't guarantee that the resource is fully accessible. |
| 93 | +
|
| 94 | +### Connectivity is successful, but the application is still not working |
| 95 | + |
| 96 | +If the connectivity tests are successful, but you're still experiencing issues in your application, you might have to check the application-level settings and configurations, as follows: |
| 97 | + |
| 98 | +- Verify that your firewall allows access from the delegated subnet to the resource. |
| 99 | +- Verify that the certificate presented by the resource is publicly trusted. |
| 100 | +- Make sure that no authentication or authorization issues exist that are preventing access to the resource. |
| 101 | + |
| 102 | +You might not be able to diagnose or resolve the issue by using the diagnostics PowerShell module. In that case, create a subnet without delegation in your virtual network, and deploy a virtual machine (VM) in that subnet. You can then use the VM to perform further diagnostics and troubleshooting steps, such as checking network traffic, analyzing logs, and testing application-level connectivity. |
0 commit comments