編輯

共用方式為

Troubleshooting the Az PowerShell module

  • 發行項

Enable debug logging

One of the first steps you should take in troubleshooting a problem with the Az PowerShell module is to enable debug logging.

To enable debug logging on a per command basis, specify the Debug parameter.

Get-AzResource -Name 'DoesNotExist' -Debug

To enable debug logging for an entire PowerShell session, you set the value of the DebugPreference variable to Continue.

$DebugPreference = 'Continue'

Announcement messages in automation scenarios

When connecting to Azure with Azure PowerShell, announcement messages are displayed using PowerShell's information stream to prevent them from altering the returned object-based output. Although we've made every effort to ensure the announcement messages don't impact your experience, there are some automation scenarios where they might affect the usage. If you experience issues, we recommend that you suppress the information stream in those scenarios:

Connect-AzAccount -Subscription '<subscription name or id>' -InformationAction Ignore

Web Account Manager (WAM)

  • The interactive sign-in method can't open a window for WAM and returns the error: User canceled authentication.
  • Azure PowerShell cmdlets can't run after logging in with a username and password or device code.
  • WAM popup window doesn't display the Work and School Account option.
  • The interactive sign-in method can't open a WAM window in the Windows PowerShell ISE console.

The workaround for these issues is to disable WAM:

Update-AzConfig -EnableLoginByWam $false
  • WAM popup window to select an account isn't easy to find. Minimize other windows to locate the popup window.

Installation

This section contains a list of solutions to common problems when installing the Az PowerShell module.

Az and AzureRM coexistence

Warning

We do not support having both the AzureRM and Az PowerShell modules installed in Windows PowerShell 5.1 at the same time.

In a scenario where you need to install both the AzureRM and Az PowerShell module on the same Windows system:

  • AzureRM must be installed only in the current user scope of Windows PowerShell 5.1.
  • Install the Az PowerShell module in PowerShell 7.2 or higher.

Warning

The AzureRM PowerShell module has been officially deprecated as of February 29, 2024. Users are advised to migrate from AzureRM to the Az PowerShell module to ensure continued support and updates.

Although the AzureRM module may still function, it's no longer maintained or supported, placing any continued use at the user's discretion and risk. Please refer to our migration resources for guidance on transitioning to the Az module.

Visual Studio

Older versions of Visual Studio may install Azure PowerShell as part of the Azure development workload, which installs the AzureRM module. Azure PowerShell can be removed using the Visual Studio installer or by using "Uninstall" in Apps & features. If you have already installed PowerShell 7.x, you may need to manually install the Az PowerShell module.

Proxy blocks connection

If you get errors from Install-Module that the PowerShell Gallery is unreachable, you may be behind a proxy. Different operating systems and network environment have different requirements for configuring a system-wide proxy. Contact your system administrator for your proxy settings and how to configure them for your environment.

PowerShell itself may not be configured to use this proxy automatically. With PowerShell 5.1 and later, configure the PowerShell session to use a proxy using the following commands:

$webClient = New-Object -TypeName System.Net.WebClient
$webClient.Proxy.Credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials

If your operating system credentials are configured correctly, this configuration routes PowerShell requests through the proxy. To have this setting persist between sessions, add the commands to your PowerShell profile.

To install the package, your proxy needs to allow HTTPS connections to www.powershellgallery.com.

Object reference not set to an instance of an object

The message "object reference not set to an instance of an object" means that you are referring to an object that's null or an Azure resource that doesn't exist or that you don't have permissions to access.

$resourceId =  '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/<resource-group-name>/providers/Microsoft.Web/sites/<webapp-name>/privateEndpointConnections/<endpoint-name>'
Get-AzPrivateEndpointConnection -ResourceId $resourceId

Get-AzPrivateEndpointConnection: Object reference not set to an instance of an object.

You can use the Get-AzResource cmdlet to verify that the specified Azure resource exists.

Get-AzResource -ResourceId $resourceId

Permission issues with AzAD cmdlets

The Az PowerShell module uses the Microsoft Graph API. Administering or managing resources in Azure with the Az PowerShell module requires the same permissions as performing the identical task from Azure portal or any other Azure command-line tool. For specific questions about permissions see the Microsoft Graph permissions reference.

Microsoft Graph query parameters

AzAd cmdlets under Az.Resources now support query parameters and search query parameters. For details about the syntax, see the previously referenced links.

Get-AzAdGroupMember doesn't return service principals

Due to limitations with the current Graph API, service principals aren't returned by Get-AzAdGroupMember in Az 7.x. As a workaround, Invoke-AzRestMethod can be used with the beta version of the Microsoft Graph API.

The following example requires the Az PowerShell module. Replace myGroupName in the first line with the name of your group.

$Group = Get-AzADGroup -DisplayName myGroupName
((Invoke-AzRestMethod -Uri "https://graph.microsoft.com/beta/groups/$($Group.id)/members").Content |
  ConvertFrom-Json).value |
  Select-Object -Property DisplayName, Id, @{label='OdataType';expression={$_.'@odata.type'}}

Command found but could not be loaded

The following message is returned by PowerShell when you attempt to run any of the Az PowerShell commands.

Connect-AzAccount: The 'Connect-AzAccount' command was found in the module 'Az.Accounts', but the module could not be loaded. For more information, run 'Import-Module Az.Accounts'.

This message occurs when you have both the Az and AzureRM PowerShell modules installed on the same Windows-based system and they exist in the $env:PSModulePath for the same version of PowerShell.

Important

When AzureRM is installed in the AllUsers scope of Windows PowerShell, it's installed in a location that's part of the $env:PSModulePath for PowerShell 7. This isn't supported due to conflicts between the AzureRM and Az PowerShell modules.

Both Az and AzureRM may coexist on the same Windows system, but only if AzureRM is installed in the CurrentUser scope of Windows PowerShell and Az installed in PowerShell 7. For more information, see Install the Az PowerShell module.

Warning

The AzureRM PowerShell module has been officially deprecated as of February 29, 2024. Users are advised to migrate from AzureRM to the Az PowerShell module to ensure continued support and updates.

Although the AzureRM module may still function, it's no longer maintained or supported, placing any continued use at the user's discretion and risk. Please refer to our migration resources for guidance on transitioning to the Az module.

On MacOS, an error returns when KeyChain authorization fails

When running Azure PowerShell on MacOS, you might encounter an error message while attempting to sign in to your Azure account from a PowerShell session.

DeviceCodeCredential authentication failed: Persistence check failed. Reason: KeyChain authorization/authentication failed. .Error code: -25293. OS error code -25293.

As a workaround for this issue, you can disable storing credentials between sessions by running the following command. After making this change however, you need to run Connect-AzAccount each time you start a new PowerShell session.

Disable-AzContextAutosave

The connection for this site is not secure

When your default browser is Microsoft Edge, you might encounter the following error when attempting to login to Azure interactively with Connect-AzAccount: "The connection for this site is not secure." To resolve this issue, visit edge://net-internals/#hsts in Microsoft Edge. Add localhost under "Delete domain security policy" and click Delete.

Service Principal IdentifierUri verified domain error

Error: Values of identifierUris property must use a verified domain of the organization or its subdomain is displayed when running New-AzADServicePrincipal or New-AzADApplication.

Due to the Microsoft Entra breaking change requiring AppId Uri in single tenant applications to require use of default scheme or verified domains you must upgrade the Az.Resources module to version 4.1.0 or later to continue using New-AzADServicePrincipal or New-AzADApplication cmdlets.

You can also upgrade to Az PowerShell module version 6.0 or greater.

Timeline

The requirement went into effect October 15, 2021.

Impacted versions

The following versions of Azure PowerShell are affected by the AzureAD breaking change:

  • Az.Resources PowerShell module version 3.5.1-preview or lesser.
  • Az PowerShell module version 5.9.0 or lesser.

If you are still encountering issues after upgrading, feel free to open an issue.

Workaround

If you can't upgrade to the PowerShell modules described previously, you may follow those steps when creating a service principal:

Other issues

If you experience a product issue with Azure PowerShell not listed in this article or require further assistance, file an issue on GitHub.