Troubleshooting common errors in Microsoft Graph PowerShell

This article explains how to determine, diagnose, and fix issues that you might encounter when using Microsoft Graph PowerShell.

Before troubleshooting any errors, make sure that you're running the most recent version of the Microsoft Graph PowerShell SDK. To check the SDK version, run:

Get-InstalledModule

The version of the Microsoft.Graph module should be the most recent compared to the latest release in the PowerShell Gallery. If your installed module isn't up to date, update it by running:

Update-Module Microsoft.Graph

Authentication and authorization errors

Authorization errors can occur due to various issues. Most of these issues generate a 403 error. The common cause for these errors is lack of permissions.

To find the permissions required for a specific cmdlet or API, use Find-MgGraphCommand cmdlet or the API permissions reference.

When you run Connect-MgGraph, you grant consent to Microsoft Graph PowerShell permissions. Here, you specify the permissions that you require using the -Scopes parameter.

For example, in the following error, the user lacks the permissions to run the New-MgServicePrincipal cmdlet.

To find the permissions required for this operation in delegated access, run:

Find-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions

Name                      IsAdmin Description                 FullDescription
----                      ------- -----------                 ---------------
Application.ReadWrite.All True    Read and write applications Allows the app to create, read, update and delete applications and service principals on your behalf. Does not allow management of consent grants.

Run Connect-MgGraph -Scopes Application.ReadWrite.All and retry to correct the error.

For app-only access, preconfigure the application permissions your app needs when you register your app. Application permissions require administrator consent, which you consent to either using the Azure portal or using a sign-up experience in your app.

Alternatively, use New-MgServicePrincipalAppRoleAssignment to assign app roles to your app.

For more info, see App-only authentication.

Using -Debug

The -Debug parameter provides a powerful way to examine a script while it's running in order to identify and correct errors in the script. The following are the important parts of a -Debug output:

1. cmdletBeginProcessing - this part allows you to confirm the cmdlet you're running and the parameter list provided to the cmdlet. For example, DEBUG: [CmdletBeginProcessing]: - Get-MgUser begin processing with parameterSet 'List1'. shows that you're running the Get-MgUser cmdlet and the parameter list is List1.
2. AuthType - is either delegated or application.
3. AuthProviderType - the type of authentication that you're using. For example, interactive, device-code, and certificate.
4. Scopes - shows all the scopes that you authenticated to for the particular application, acquired by decoding the access token.
5. HTTP request - comprises of:
   1. Method - could be GET, POST, PUSH, UPDATE
   2. URI - URI changes based on the cloud you connected to and the version of the SDK you're running.
   3. Body - shows the body of your request.
6. HTTP response - comprises of the following information:
   1. Status code - this part provides the error code returned.
      1. OK: the command run successfully.
      2. Bad request: take the URI and call it via Invoke-MgGraphRequest to determine if it's a service or a client issue.
   2. Headers - The most important headers are the request-id and date. These headers help the support team to determine the cause of the failure. Use this ID and timestamp as you log any issues for the support team to troubleshoot.
   3. Body - shows what the service returns. The most important part of the body is the @odata.nextLink, which provides a link to fetch the next page when the result is in multiple pages. If the request fails, the body will contain the error code and the error message.

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

Get-MgUser -UserId 'DoesNotExist' -Debug

The following image shows a sample output of this command.

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

$DebugPreference = 'Continue'

Using the -Debug parameter is helpful when you want to open a support ticket. It will allow you to get the request-id and Date that is required when logging such issues.

Using -ErrorVariable

When you run a PowerShell cmdlet and an error occurs, the error record will be appended to the automatic variable named $error. When you use the -ErrorVariable parameter in a call to a command, the error is assigned to the variable name that you specify. Even when you use the -ErrorVariable parameter, the $error variable is still updated.

By default, the -ErrorVariable parameter will overwrite the variable with the name that you specify. If you want to append an error to the variable instead of overwriting it, you can put a plus sign (+) in front of the variable name. For example,

Get-MgUser -UserId 'f' -ErrorVariable MyError
$MyError.Count # Should be 1
Get-MgUser -UserId 'doesNotExist' -ErrorVariable +MyError
$MyError.Count # Should be 2

Using ErrorAction

The -ErrorAction common parameter allows you to specify which action to take if a command fails. The available options are: Stop*, Continue, SilentlyContinue, Ignore, or Inquire.

When you specify the -ErrorAction parameter during a call to a command, the specified behavior will override the $ErrorActionPreference variable in Windows PowerShell

By default, Windows PowerShell uses an error action preference of Continue, which means that errors will be written out to the host, but the script will continue to execute. If you set $ErrorActionPreference to Stop or if you use Stop as the parameter value for -ErrorAction, Windows PowerShell will stop the script execution at the point an error occurs.

Next steps

For more information related to troubleshooting, see:

• API reliability & support
• API permissions reference