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. Each part of the -Debug output provides key information that helps you diagnose and resolve issues more efficiently. The following section lists 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, PUT, PATCH
   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 the Get-MgUser -UserId 'DoesNotExist' -Debug 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 global automatic variable named $error. This variable is available in every PowerShell session and stores a collection of error records that have occurred during the session. When you use the -ErrorVariable parameter in a call to a command, the error is also 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 overwrites the variable 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 # MyError should contain 1 error
Get-MgUser -UserId 'doesNotExist' -ErrorVariable +MyError
$MyError.Count # MyError should now contain 2 errors

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 overrides the $ErrorActionPreference variable in Windows PowerShell.

By default, Windows PowerShell uses an error action preference of Continue, which means that errors is written out to the host, but the script continues to execute. The $ErrorActionPreference variable is a global setting that determines the default error handling behavior for all commands in the session, unless overridden by the -ErrorAction parameter on a specific command. If you set $ErrorActionPreference to Stop or if you use Stop as the parameter value for -ErrorAction, Windows PowerShell stops the script execution at the point an error occurs.

Next steps

For more information related to troubleshooting, see:

• API reliability & support: Learn best practices for ensuring reliable API usage and how to get support for Microsoft Graph issues.
• API permissions reference: Find detailed information about the permissions required for different Microsoft Graph APIs and cmdlets.