Merge pull request #9244 from MicrosoftDocs/main

Auto push to live 2025-07-01 02:43:08

Author: Deland-Han

support/azure/automation/runbooks/troubleshoot-runbook-execution-issues.md

@@ -0,0 +1,73 @@
+---
+title: Troubleshoot Runbook Execution Issues in Azure Automation
+description: Provides troubleshooting guidance on runbook execution issues in Azure Automation.
+ms.date: 07/01/2025
+ms.service: azure-automation
+ms.reviewer: adoyle, v-weizhu
+ms.custom: sap:Runbook not working as expected
+---
+# Troubleshoot runbook execution issues in Azure Automation
+
+Process automation in Azure Automation allows you to create and manage PowerShell, a PowerShell workflow, and graphical runbooks. Azure Automation executes your runbooks based on the logic defined within them. This article provides troubleshooting guidance on runbook execution issues in Azure Automation.
+
+> [!NOTE]
+>
+> - If you use the Newtonsoft.Json v10, be sure to import this module explicitly so that your PowerShell 5.1 and PowerShell 7.1 runbooks that have a dependency on this version of the module function correctly.
+> - PowerShell 7.1 is no longer supported by the parent product PowerShell. We recommend creating PowerShell 7.2 runbooks for long-term support. Learn more about [PowerShell 7.2 runbooks](/azure/automation/automation-runbook-types).
+> - If none of the following solutions resolves your issue, see [Data to collect when opening a case for Microsoft Azure Automation](/azure/automation/troubleshoot/collect-data-microsoft-azure-automation-case) before opening a support case.
+> - Azure Automation enables the recovery of runbooks deleted in the last 29 days. You can restore the deleted runbook by running a PowerShell script as a job in your Automation account. For more information, see [Restore deleted runbook](/azure/automation/manage-runbooks#restore-deleted-runbook).
+
+## Troubleshoot error code 400, 403, and 429
+
+|Error|Solution|
+|---|---|
+|`400 Bad Request: This webhook is expired or disabled`|To resolve this error, see [400 Bad Request status when calling a webhook](/azure/automation/troubleshoot/runbooks#expired%20webhook).|
+|`The remote server returned an error: (403) Forbidden`|To resolve this error, see [Access blocked to Azure Storage, or Azure Key Vault, or Azure SQL](/azure/automation/troubleshoot/runbooks#scenario-access-blocked-to-azure-storage-or-azure-key-vault-or-azure-sql).|
+|`this.Client.SubscriptionId cannot be null`|To resolve this error, see [Runbook fails with "this.Client.SubscriptionId cannot be null." error message](/azure/automation/troubleshoot/runbooks#runbook-fails-no-permission).|
+|`ErrorCode: AuthorizationFailed` </br></br>`StatusCode: 403`|To resolve this error, see [Runbooks fail when dealing with multiple subscriptions](/azure/automation/troubleshoot/runbooks#runbook-auth-failure).|
+|`429: The request rate is currently too large. Please try again.`|To resolve this error, see [429: The request rate is currently too large](/azure/automation/troubleshoot/runbooks#429).|
+
+## Troubleshoot errors related to cmdlet not recognized, sign-in required, or subscription missing
+
+|Error|Solution|
+|---|---|
+|Runbooks fail with the error `The subscription named <subscription name> cannot be found.`|This error can occur when the runbook doesn't use a managed identity to access Azure resources. To resolve this error, see [Unable to find the Azure subscription](/azure/automation/troubleshoot/runbooks#unable-to-find-subscription).|
+|`Your Azure credentials haven't been set up or have expired, please run connect-azureRmAccount to set up your azure credentials.`|This error can occur when you don't use a managed identity. To resolve this error, use a managed identity.|
+|`Command not recognized.`|This error often occurs when modules aren't imported or are out of date. Make sure that dependent modules in your script are [imported into Azure Automation](/azure/automation/automation-runbook-gallery#modules-in-the-powershell-gallery) and are the correct version. If the module is in your Automation account, there might be an issue loading it into the sandbox. Try adding an explicit `import-module` statement at the beginning of your runbook.|
+|`Forbidden with client authentication scheme 'anonymous'`.|This error occurs when using credentials in an Azure Automation sandbox. To resolve this error, use a managed identity.|
+|`Unable to require token for tenant <tenant-id>`.|This error occurs when using credentials in an Azure Automation sandbox. To resolve this error, use a managed identity.|
+|`Server failed to authenticate the request.`|This error occurs when using credentials in an Azure Automation sandbox. To resolve this error, use a managed identity.|
+|Errors when using the `Connect-AzAccount` cmdlet.|To resolve this issue, see [Sign-in to Azure account failed](/azure/automation/troubleshoot/runbooks#sign-in-failed).|
+|`The term 'Connect-AzAccount' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if the path was included verify that the path is correct and try again.`|To resolve this error, see [Term not recognized as the name of a cmdlet, function, or script](/azure/automation/troubleshoot/runbooks#not-recognized-as-cmdlet).|
+|Cmdlet fails in PnP PowerShell runbook on Azure Automation.|To resolve this issue, see [Cmdlet fails in PnP PowerShell runbook on Azure Automation](/azure/automation/troubleshoot/runbooks#scenario-cmdlet-fails-in-pnp-powershell-runbook-on-azure-automation).|
+|`<cmdlet name>: The term <cmdlet name> is not recognized as the name of a cmdlet, function, script file, or operable program.`|To resolve this error, see [Cmdlet not recognized when executing a runbook](/azure/automation/troubleshoot/runbooks#cmdlet-not-recognized).|
+
+## Troubleshoot issues with suspended runbooks, job failures, stopped runbooks, hybrid workers, and subscriptions
+
+|Issue|Solution|
+|---|---|
+|Runbook is suspended or unexpectedly fails.|Review your [Job Statuses](/azure/automation/automation-runbook-execution#job-statuses) for runbook statuses and possible causes. [Add more output](/azure/automation/automation-runbook-output-and-messages#message-streams) to identify what happens before the runbook is suspended. [Handle any exceptions](/azure/automation/automation-runbook-execution#exceptions) thrown by your job. Retry your job when certain exceptions occur, such as WebSocket exceptions, to prevent transient network failures from causing runbook failures. If you have issues with a cmdlet, you might find more information with the service you try to use through the cmdlet. For example, the `New-AzAnalysisServicesServer` cmdlet related issues might end up with the Analysis Services team.|
+|Job was tried three times, but it failed.|Check the [Automation Limits](/azure/azure-subscription-service-limits#azure-automation-limits). If the limitation applies to Azure sandboxes only, consider moving to a [hybrid worker](/azure/automation/automation-hybrid-runbook-worker).|
+|Runbooks were working but stopped.|[Make sure to use a managed identity](/azure/automation/migrate-run-as-accounts-managed-identity#cert-renewal). If [using webhooks to start runbooks](/azure/automation/automation-webhooks#renew-webhook), make sure the webhook hasn't expired.|
+|Issues when using a hybrid worker.|To resolve these issues, see [Hybrid Runbook Worker troubleshooting guide](/azure/automation/troubleshoot/hybrid-runbook-worker).|
+|Runbook is stuck.|If you can't stop a runbook job in the Azure portal, try stopping it by using the PowerShell cmdlet `Stop-AzureRmAutomationJob` or `Stop-AzAutomationJob`.|
+|Can't start or schedule a runbook.|To resolve this issue, make sure your runbook [is published](/azure/automation/manage-runbooks#publish-a-runbook).|
+|Issues when using cmdlets that depend on binaries.|Some cmdlets rely on binaries, such as Microsoft Data Access Components (MDAC) or the Azure Fabric SDK. These cmdlets can't be run in the Azure Automation sandbox and must be executed through [a hybrid worker](/azure/automation/automation-hybrid-runbook-worker).|
+|Issues when there are multiple subscriptions in a runbook.|To manage Azure resources across several subscriptions with Azure Automation, see [Dealing with multiple subscriptions](/azure/automation/troubleshoot/runbooks#runbook-auth-failure) to prevent errors.|
+
+## Troubleshoot common issues
+
+The following table helps you troubleshoot common issues with runbooks:
+
+|Issue|Solution|
+|---|---|
+|Unable to create a new Automation job in the West Europe region.|This issue occurs because of scalability limits with the Automation service in the West Europe region. To resolve it, follow the steps in [Unable to create new Automation job in West Europe region](/azure/automation/troubleshoot/runbooks#scenario-unable-to-create-new-automation-job-in-west-europe-region).|
+|Runbook bugs or Azure Automation issues.|To learn how to troubleshoot common scenarios, see [Troubleshoot runbook issues](/azure/automation/troubleshoot/runbooks#runbook-fails).|
+|Runbook output and message issues.| To resolve such issues, see [Retrieve runbook output and messages](/azure/automation/automation-runbook-output-and-messages#runbook-output).|
+|PowerShell module issues in Azure Automation.|To resolve such issues, see [Update Azure PowerShell modules in Automation](/azure/automation/automation-update-azure-modules).|
+
+## References
+
+- [How to start a runbook in Azure Automation](/azure/automation/start-runbooks)
+- [PowerShell runbooks](/azure/automation/automation-runbook-types#powershell-runbooks)
+- [Set-AzSqlDatabase](/powershell/module/az.sql/set-azsqldatabase) that sets properties for a database or move an existing database into an elastic pool

support/azure/automation/toc.yml

@@ -2,13 +2,15 @@
   href: welcome-automation.yml
 - name: Runbook not working as expected
   items:
-  - name: Troubleshoot error codes during runbook execution
-    href: runbooks/error-running-powershell-runbook.md
   - name: Runbook jobs get suspended
     href: runbooks/runbook-job-suspended.md
+  - name: Troubleshoot error codes during runbook execution
+    href: runbooks/error-running-powershell-runbook.md
   - name: Troubleshoot issues with python packages
     href: runbooks/error-running-python-runbook.md
   - name: Troubleshoot issues with runbook execution start time
     href: runbooks/job-not-start-as-expected.md
+  - name: Troubleshoot runbook execution issues
+    href: runbooks/troubleshoot-runbook-execution-issues.md
   - name: Troubleshoot runbook execution issues when using PowerShell
     href: runbooks/powershell-job-script-cmdlets-not-working.md

support/azure/automation/welcome-automation.yml

@@ -21,7 +21,7 @@ landingContent:
   - title: Runbook not working as expected
     linkLists:
       - linkListType: how-to-guide
-        links:                                                                  
+        links:    
           - text: Runbook jobs get suspended
             url: runbooks/runbook-job-suspended.md     
           - text: Troubleshoot error codes during runbook execution
@@ -30,5 +30,7 @@ landingContent:
             url: runbooks/error-running-python-runbook.md
           - text: Troubleshoot issues with runbook execution start time
             url: runbooks/job-not-start-as-expected.md
+          - text: Troubleshoot runbook execution issues
+            url: runbooks/troubleshoot-runbook-execution-issues.md      
           - text: Troubleshoot runbook execution issues when using PowerShell
             url: runbooks/powershell-job-script-cmdlets-not-working.md

support/entra/entra-id/app-integration/msal-client-exception-failed-to-get-user-name.md

@@ -0,0 +1,80 @@
+---
+title: MsalClientException - Failed to Get User Name
+description: Resolves the Failed to get user name error when an application uses Integrated Windows Authentication (IWA) with Microsoft Authentication Library (MSAL).
+ms.service: entra-id
+ms.date: 07/01/2025
+ms.reviewer: willfid, v-weizhu
+ms.custom: sap:Developing or Registering apps with Microsoft identity platform
+---
+
+# Microsoft.Identity.Client.MsalClientException: Failed to get user name
+
+This article provides a solution to the "Failed to get user name" error that occurs when an application uses Integrated Windows Authentication (IWA) together with Microsoft Authentication Library (MSAL).
+
+## Symptoms
+
+When your application uses IWA together with MSAL, if calling the `AcquireTokenByIntegratedWindowsAuth` method as follows:
+
+```csharp
+result = await app.AcquireTokenByIntegratedWindowsAuth(scopes)
+```
+
+You encounter one of the following errors:  
+
+- > Microsoft.Identity.Client.MsalClientException: Failed to get user name —>  
+  > System.ComponentModel.Win32Exception: No mapping between account names and security IDs was done 
+
+- > Microsoft.Identity.Client.MsalClientException: Failed to get user name —>  
+  > System.ComponentModel.Win32Exception: Access Denied
+
+## Cause
+
+The error originates from Windows. It occurs because MSAL calls the [GetUserNameEx](/windows/win32/api/secext/nf-secext-getusernameexa) function from `secur32.dll`. For more information, see [MSAL WindowsNativeMethods.cs - GetUserNameEx](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/01ecd12464007fc1988b6a127aa0b1b980bca1ed/src/client/Microsoft.Identity.Client/Platforms/Features/DesktopOS/WindowsNativeMethods.cs#L66).
+
+## Solution
+
+> [!NOTE]
+> Before you begin, ensure the following minimum requirements are met:
+>
+> - Run the application as a local Active Directory user, not a local computer user account.
+> - The device running the application is joined to the domain.
+
+To resolve this issue, pass the username to `AcquireTokenByIntegratedWindowsAuth`.
+
+If the username is known beforehand, you can manually pass it to MSAL as follows:
+
+```csharp
+result = await app.AcquireTokenByIntegratedWindowsAuth(scopes).WithUsername("<service-account>@contoso.com")
+```
+
+If the username isn't known beforehand, dynamically retrieve the username and then pass it to `AcquireTokenByIntegratedWindowsAuth` by using one of the following methods:
+
+- Use `System.Security.Principal.WindowsIdentity.GetCurrent()`
+
+    Here's the code example:
+
+    ```csharp
+    string username = System.Security.Principal.WindowsIdentity.GetCurrent().Name;
+    result = await app.AcquireTokenByIntegratedWindowsAuth(scopes).WithUsername(username)
+    ```
+
+    > [!NOTE]
+    > If the returned username doesn't include a domain, this method fails and returns different errors. For proper integration with Microsoft Entra ID, you must pass the username in the format of a user principal name.
+
+- Use `PublicClientApplication.OperatingSystemAccount.Username`
+
+    Here's the code example:
+
+    ```csharp
+    string username = PublicClientApplication.OperatingSystemAccount.Username;
+    result = await app.AcquireTokenByIntegratedWindowsAuth(scopes).WithUsername(username)
+    ```
+
+    > [!NOTE]
+    > This method tries to access the Windows Account Broker to sign the user into the device. It doesn't work if the application runs on Internet Information Services (IIS) or Windows Server.
+
+## Reference
+
+[Using MSAL.NET with Integrated Windows Authentication (IWA)](/entra/msal/dotnet/acquiring-tokens/desktop-mobile/integrated-windows-authentication)
+
+[!INCLUDE [Azure Help Support](../../../includes/azure-help-support.md)]

support/entra/entra-id/toc.yml

@@ -67,6 +67,8 @@
         href: app-integration/troubleshoot-error-idx10501-aspnet-b2c.md
       - name: Infinite sign-in loop issue with ASP.NET applications
         href: app-integration/asp-dot-net-application-infinite-sign-in-loop.md
+      - name: MsalClientException - Failed to get user name
+        href: app-integration/msal-client-exception-failed-to-get-user-name.md
       - name: No account or login hint was passed to the AcquireTokenSilent
         href: app-integration/no-account-login-hint-passed-acquire-token-silent.md
       - name: Package Inspector for MSAL Android Native
@@ -335,6 +337,8 @@
         href: users-groups-entra-apis/b2c-or-tenant-premium-license-sign-in-activities.md
    - name: Problem with using the Graph SDK - libraries
      items:
+      - name: IDX14102 error - Unable to decode the header
+        href: users-groups-entra-apis/unable-to-decode-header-error.md
       - name: Python scripts making requests are detected as web crawlers
         href: users-groups-entra-apis/python-scripts-microsoft-graph-requests-detected-as-web-crawler.md
 - name: Microsoft Entra User Provisioning and Synchronization

support/entra/entra-id/users-groups-entra-apis/unable-to-decode-header-error.md

@@ -0,0 +1,43 @@
+---
+title: IDX14102 Error When Using Microsoft Graph PowerShell
+description: Resolves an error that occurs when you run the Microsoft Graph PowerShell cmdlet Connect-MgGraph.
+ms.date: 07/01/2025
+ms.service: entra-id
+ms.custom: sap:Problem with using the Graph SDK - libraries
+ms.reviewer: adoyle, willfid, nualex, v-weizhu
+---
+
+# Microsoft Graph PowerShell throws error "IDX14102: Unable to decode the header"
+
+This article provides solutions to the error "IDX14102: Unable to decode the header" that occurs when you use Microsoft Graph PowerShell.
+
+## Symptoms
+
+When running the Microsoft Graph PowerShell command `Connect-MgGraph -AccessToken $token`, you receive the following error:
+
+> IDX14102: Unable to decode the header
+
+## Cause
+
+This error occurs because an invalid access token is passed to the `AccessToken` parameter of the `Connect-MgGraph` cmdlet. This problem often occurs when the token is obtained via Azure PowerShell's `Get-AzAccessToken` cmdlet and passed as a `SecureString`. This behavior is observed starting with version 5.0.0 of the `Az.Accounts` module. Starting from Microsoft Graph PowerShell version 2.28.0, the `Connect-MgGraph` command accepts only a plain string as the `AccessToken` parameter.
+
+## Solution
+
+Here are two solutions for resolving this issue:
+
+- Make sure the access token passed to the `AccessToken` parameter of the `Connect-MgGraph` cmdlet is valid.
+
+    For more information about access tokens, see [Access tokens in the Microsoft identity platform](/entra/identity-platform/access-tokens).
+
+- If you use the `Get-AzAccessToken` cmdlet to obtain the access token, use one of the following methods:
+
+  - Downgrade `Az.Accounts` to version 4.2.0 to avoid the token being returned as a `SecureString`.
+  - Convert the token from `SecureString` to `String`:
+
+    ```azurepowershell
+    $microsoftGraphToken = Get-AzAccessToken -ResourceUrl "https://graph.microsoft.com"
+    
+    Connect-MgGraph -AccessToken (ConvertFrom-SecureString -SecureString $microsoftGraphToken.Token -AsPlainText)
+    ```
+
+[!INCLUDE [Azure Help Support](../../../includes/azure-help-support.md)]