The HybridRegistration Module was not found: Hybrid Runbook Error

featured image

While setting up a new Hybrid Runbook Worker, I encountered a new error: “The HybridRegistration Module was not Found. Please ensure the Microsoft Monitoring Agent was installed correctly”. I have to say this was incredibly frustrating because the solution ultimately had nothing to do with what the error suggested.

While running the Hybrid Runbook Worker setup script, it had failed at the HybridRegistration Module installation point. While trying to fix this issue, the only indication that I had found for why this happened was in a single Stack Overflow post, so I decided I was going to write about it here. In this post I am going to break down the process I used to solve this error.


Please understand that the content herein is for informational purposes only. This existence and contents shall not create an obligation, liability or suggest a consultancy relationship. In further, such shall be considered as is without any express or implied warranties including, but not limited to express and implied warranties of merchantability, fitness for a particular purpose and non-infringement. There is no commitment about the content within the services that the specific functions of the services or its reliability, applicability or ability to meet your needs, whether unique or standard. Please be sure to test this process fully before deploying in ANY production capacity, and ensure you understand that you are doing so at your own risk.

Table of Contents

The Error & Troubleshooting
Privatelink DNS Registration
Manual Resolution of HybridRegistration Module Missing

The Error & Troubleshooting

In this scenario, I had previously configured my Azure Automation account to have a Privatelink connection to give it internet access via our Azure VNet. I had not configured it originally to be used with a Hybrid Worker Group. This turned out to be a key point later. Fast forward to the present and I decided to add a Hybrid Worker Group to this Azure Automation account. I now needed access to on premises SQL Servers for my scripts and wanted to put the Hybrid Worker to the test for this use case.

Error #1

While running the script for the Hybrid Worker setup, I received this error: “The HybridRegistration Module was not Found. Please ensure the Microsoft Monitoring Agent was installed correctly”. This had blocked the installation from continuing and prevented me from using Hybrid Worker.

The HybridRegistration Module was not Found. Please ensure the Microsoft Monitoring Agent was installed correctly
The HybridRegistration Module was not Found. Please ensure the Microsoft Monitoring Agent was installed correctly

Upon seeing this, my first thought was that the Microsoft Monitoring Agent installation must’ve failed, and I may need to install it manually. I looked at the installed applications and saw it was installed. Ok, so then I looked at the version installed and confirmed it was indeed the latest version, and its installation date was that same day. I uninstalled the Microsoft Monitoring Agent (MM Agent), then re-ran the setup script again. MM Agent was reinstalled, yet the same error persisted.

Error #2

I then decided to look through the manual installation instructions and see where it had failed, and picked up those steps to see if I could get more information. I confirmed each step seemed to work correctly up until the HybridRegistration Module being installed. I then went to manually install the aforementioned custom PowerShell module. Upon doing so I discovered that it was already installed and available. Continuing through the instructions, I went to manually run the “Add-HybridRunbookWorker” cmdlet. I gathered all the required information, saved them to variables, then proceeded to run the Add-HybridRunbookWorker cmdlet. I then received this error.

add-HybridRunbookWorker: could not authenticate the private link packet
Add-HybridRunbookWorker: could not authenticate the private link packet

After confirming I had the right address, and access key, I decided it must either be a networking error or a DNS error. Time to investigate the Privatelink Connection and confirm everything was working as expected.

Privatelink DNS Registration

If you have been around IT for a while, you’ve probably heard that every problem is DNS. While that is obviously hyperbole, it’s not that far from the truth. A quick internet search of that last error turned up this Stack Exchange post. I went back to my Privatelink connector in my Azure Automation account, and I realized that when I initially created this Privatelink connector I chose not to “Integrate with private DNS Zone“. DNS strikes again!

Missing the Custom DNS records
Missing the Custom DNS records

I went through this screen, added a new DNS configuration, and then waited. And waited. And waited some more. After about 4 hours I still could not get the privatelink custom DNS address to resolve with nslookup from the Hybrid Worker.

Re-reading that Stack Exchange post I mentioned I noticed they mentioned needing to completely recreate the NIC and have it register with DNS during creation. It seemed strange to me it was different, but perhaps there is a priority to these things, and I was sick of waiting.

After recreating the Privatelink NIC on the Automation Account, telling it to “Integrate with private DNS Zone” this time, it only took about 10 minutes before nslookup on the Hybrid Worker found the address. I was able to follow the steps in the next section to finish Hybrid Worker setup and begin using my new Hybrid Worker.

‘On Premises’ Additional Steps

I ended up seeing this same error in my ‘on-prem’ lab. I’ll be working on a full write up for how to configure the DNS settings to access Privatelink Azure resources from on premises in another post, but there is an additional step to do when you are on prem vs in Azure with your Hybrid Worker. I am assuming you already have that part setup if you are this far. If not, check back later and I will have a link to the full setup.

You will need to manually add a custom entry into your local DNS records for this Automation Account if your Hybrid worker lives on prem. Open DNS on your DC or DNS server. KEEP IN MIND! This is not the full setup for DNS for Privatelink connections from on-prem resources. If that is not set up, you need to go through that first. The full Microsoft documentation can be found here.

  1. You need to add new entries for your Privatelink nic’s to have them found by the Hybrid Worker.
DNS configurations for automation account to be added to on prem DNS
  1. Right click the DNS zone and add a new host record. Add each of these records you see in your automation account privatelink DNS records.
entry number one for automation account privatelink
Entry #1
entry number two for automation account privatelink
Entry #2
  1. Once you are finished, your DNS zone should look like this.
Correct records for privatelink configuration

Now run “repadmin /syncall” on the DC to replicate DNS records, and after a couple minutes your NSLOOKUP should be able to resolve the address for your privatelink connection. If that is working, you are ready to finish the Hybrid Worker setup.

Manual Resolution of HybridRegistration Module Missing

Now that DNS is all ready to go, we can resume our Hybrid Worker setup. Grab this code snippet to get started. You’ll need to navitgate to this path (“C:\Program Files\Microsoft Monitoring Agent\Agent\AzureAutomation\<version>\HybridRegistration”) to figure out what the path will be in this code below.

You can find the URL and KEY values in the Keys section of your Automation Account.

keys and storage url location
cd "C:\Program Files\Microsoft Monitoring Agent\Agent\AzureAutomation\*\HybridRegistration"
Import-Module .\HybridRegistration.psd1

$key = "StorageKey"
$Url = "storageURL"
$rgname = "ResourceGroupName"

Add-HybridRunbookWorker –GroupName $rgname -Url $url -Key $key

As long as this completes with no errors you should be all set! The Hybrid Worker should be registered correctly, and you should be able to see it in the Hybrid Worker group page.


I hope this helps you resolve this issue for yourself. So far the two times I have seen it, it worked for me. The automated Hybrid Worker setup method works really well and for the most part it doesn’t really have many issues. After doing this a few times, you’ll probably remember to set this error correctly the first time.

Let me know what you think and if this worked for you. Hit me up on Twitter @SeeSmittyIT to let me know what you thought of this post. Or if you are avoiding the bird site, I’m also posted up on Mastodon @[email protected]. Thanks for reading!


Curtis Smith works in IT with a primary focus on Mobile Device Management, M365 Apps, and Azure AD. He has certifications from CompTIA and Microsoft, and writes as a hobby.

View all posts by Smitty →