|
| 1 | +--- |
| 2 | +title: Troubleshoot Hybrid Runbook Worker Job Failures in Azure Automation |
| 3 | +description: Discusses some common issues that might occur when you run a runbook on Hybrid Runbook Worker. |
| 4 | +ms.date: 06/13/2025 |
| 5 | +ms.reviewer: adoyle |
| 6 | +ms.service: azure-automation |
| 7 | +ms.custom: sap:Runbook not working as expected |
| 8 | +--- |
| 9 | + |
| 10 | +# Hybrid Runbook Worker job isn't working as expected |
| 11 | + |
| 12 | +This article provides guidance for troubleshooting and resolving issues that affect Hybrid Runbook Worker in Azure Automation. |
| 13 | + |
| 14 | +> [!NOTE] |
| 15 | +> Azure Automation enables the recovery of runbooks that are deleted in the past 29 days. For more information, see [Restore deleted runbook](/azure/automation/manage-runbooks#restore-deleted-runbook). |
| 16 | +
|
| 17 | +## Troubleshoot connectivity issues |
| 18 | + |
| 19 | +Connectivity problems are a common cause of issues that affect runbooks. Use the [Test Cloud Connectivity tool](/azure/azure-monitor/agents/agent-windows-troubleshoot?tabs=UpdateMMA#connectivity-issues) to verify that your environment is correctly configured. |
| 20 | + |
| 21 | +## General troubleshooting |
| 22 | + |
| 23 | +| **Issue** | **Resolution** | |
| 24 | +|----------|----------------| |
| 25 | +| Runbooks behave differently on a hybrid worker than in Azure Automation. | See [Runbook permissions](/azure/automation/automation-hrw-run-runbooks#runbook-permissions) for information about authentication differences. | |
| 26 | +| Error: No certificate was found. | Follow the "[No Certificate Found](/azure/automation/troubleshoot/hybrid-runbook-worker#no-cert-found)" section in the troubleshooting guide. | |
| 27 | +| You need to troubleshoot a custom runbook. | See [Troubleshoot runbook issues](/azure/automation/troubleshoot/runbooks). | |
| 28 | +| You need to check job status. | Review [job details and statuses](/azure/automation/automation-runbook-execution#job-statuses). | |
| 29 | +| Hybrid worker doesn't run jobs or is unresponsive. | Troubleshoot by using [Hybrid Runbook Worker diagnostics](/azure/automation/troubleshoot/hybrid-runbook-worker). | |
| 30 | +| Runbooks suddenly stop working. | Make sure that you [migrated to managed identity](/azure/automation/migrate-run-as-accounts-managed-identity?tabs=sa-managed-identity#cert-renewal) and that webhooks aren't expired. | |
| 31 | +| Need help with passing parameters into a webhook. | See [Start a runbook from a webhook](/azure/automation/automation-webhooks#parameters-used-when-the-webhook-starts-a-runbook). | |
| 32 | +| You want to use both `Az` and `AzureRM` modules in runbook. | This scenario isn't supported. Use only [Az modules in runbooks](/azure/automation/automation-update-azure-modules). | |
| 33 | +| Can't start or schedule a runbook. | Verify that the runbook is in a [published state](/azure/automation/manage-runbooks#publish-a-runbook). | |
| 34 | +| Runbook is suspended or failed unexpectedly. | Review [job statuses](/azure/automation/automation-runbook-execution#job-statuses). Add logging to the runbook by using [output streams](/azure/automation/automation-runbook-output-and-messages#working-with-message-streams). If the job fails three times, check [the automation limits](/azure/azure-resource-manager/management/azure-subscription-service-limits#automation-limits) and consider using a [Hybrid Worker](/azure/automation/automation-hybrid-runbook-worker). | |
| 35 | + |
| 36 | + |
| 37 | +### Windows Hybrid Runbook Worker issues |
| 38 | + |
| 39 | +| **Issue** | **Resolution** | |
| 40 | +|-----------|----------------| |
| 41 | +| Event 4502 appears in the Operations Manager log. | See [Event 4502](/azure/automation/troubleshoot/hybrid-runbook-worker#event-4502). | |
| 42 | +| Script using `Connect-MsolService` can't connect to Microsoft 365. | See [Sandbox can't connect to Microsoft 365](/azure/automation/troubleshoot/hybrid-runbook-worker#scenario-orchestratorsandboxexe-cant-connect-to-microsoft-365-through-proxy). | |
| 43 | +| Machine is running but not sending heartbeat data. | See [Hybrid worker not reporting](/azure/automation/troubleshoot/hybrid-runbook-worker#corrupt-cache). | |
| 44 | + |
| 45 | + |
| 46 | +### Linux Hybrid Runbook Worker issues |
| 47 | + |
| 48 | +| **Issue** | **Resolution** | |
| 49 | +|-----------|----------------| |
| 50 | +| Unexpected password prompt appears when using `sudo`. | See [Linux runbook worker prompts for password](/azure/automation/troubleshoot/hybrid-runbook-worker#prompt-for-password). | |
| 51 | +| Log file shows "The specified class does not exist." | See [Class does not exist error](/azure/automation/troubleshoot/hybrid-runbook-worker#class-does-not-exist). | |
| 52 | +| Linux job is stuck in **Running** state | 1. Switch to `sudo` permissions: `sudo su`<br>2. Make sure that the `hwd` service is running: `systemctl status hwd.service`<br>3. Open the following file in Hybrid Worker: `vi /lib/systemd/system/hwd.service`<br>4. Update the setting from `CPUQuota=25%` to `CPUQuota=` to make the usage unrestricted, as shown in the following example: <br><br>`[Unit]`<br>`Description=HW Service`<br>`After=network.target`<br>`[Service]`<br>`Type=simple`<br>`ExecStart=/usr/bin/python3 .../automationWorkerStarterScript.py`<br>`TimeoutStartSec=5`<br>`Restart=always`<br>`RestartSec=10s`<br>`TimeoutStopSec=600`<br>`CPUQuota=`<br>`KillMode=process`<br>`[Install]`<br>`WantedBy=multi-user.target`<br><br> 5. Restart the `hwd` service: <br>`systemctl daemon-reload` <br> `systemctl restart hwd.service`<br>| |
| 53 | + |
| 54 | +## Other error messages |
| 55 | + |
| 56 | +| **Error** | **Resolution** | |
| 57 | +|-----------|----------------| |
| 58 | +| "The subscription cannot be found" | This error usually means that the runbook isn't using a managed identity. Follow the steps in [Unable to find subscription](/azure/automation/troubleshoot/runbooks#unable-to-find-subscription). | |
| 59 | +| "Strong authentication enrollment is required." | See [Authentication to Azure failed due to MFA](/azure/automation/troubleshoot/runbooks#auth-failed-mfa). | |
| 60 | +| "No permission" or similar error | Make sure that the [managed identity has appropriate permissions](/azure/role-based-access-control/role-assignments-portal). | |
| 61 | + |
| 62 | +## Reference |
| 63 | + |
| 64 | +- [Automation Hybrid Runbook Worker overview](/azure/automation/automation-hybrid-runbook-worker) |
| 65 | +- [Deploy a Windows Hybrid Runbook Worker](/azure/automation/automation-windows-hrw-install) |
| 66 | +- [Deploy a Linux Hybrid Runbook Worker](/azure/automation/automation-linux-hrw-install) |
| 67 | +- [Run runbooks on a Hybrid Runbook Worker](/azure/automation/automation-hrw-run-runbooks) |
0 commit comments