Microsoft 365 Groups are great for collaboration, while also providing some distribution list (DL) capabilities. Exchange Online provides a native way to upgrade distribution lists to Microsoft 365 Groups; however, sometimes DLs don’t upgrade as expected and in these cases, there might be no feedback provided to the admin as to why.

To help customers with these types of failures, we created a PowerShell-based tool, DLT365Groupsupgrade, that checks the DL being upgraded for any blockers that might cause upgrade failure.

Using the DL Upgrade Troubleshooter

In this example, we’re upgrading a DL called DemoDL; however, it won’t upgrade, and no error is reported:

Running the tool on DemoDL shows a blocker that causes the upgrade process to fail:

The blocker is an existing email address policy (EAP). The DL’s PrimarySmtpAddress is “@Hazem.exohybridlabs.com” but the EnabledPrimarySMTPAddressTemplate on the EAP is “@hazem.exohybridlabs.com.” This indicates that the EAP comparison condition is case-sensitive.

There are 2 ways to remove this blocker. You can recreate the DL with the correct primary smtp address, or you can use the following steps to remove the SMTP alias containing “@Hazem.exohybridlabs.com.”

Connect to Exchange Online PowerShell.

Use Set-DistributionGroup to replace the primary SMTP address with another accepted domain in your organization:

Set-DistributionGroup DemoDl -PrimarySmtpAddress DemoDl@anotheraccepteddomain.com

Use Get-DistributionGroup to validate the change:

Get-DistributionGroup |fl PrimarySmtpAddress,EmailAddresses

Use Set-DistributionGroup to remove the wrong SMTP address for Hazem.exohybridlabs.com:

Set-DistributionGroup DemoDl -EmailAddresses @{remove="DemoDl@Hazem.exohybridlabs.com"}

Use Get-DistributionGroup to validate the change:

Get-DistributionGroup |fl PrimarySmtpAddress,EmailAddresses

Use Set-DistributionGroup to add the correct SMTP address for hazem.exohybridlabs.com:

Set-DistributionGroup DemoDl -EmailAddresses @{add="DemoDl@hazem.exohybridlabs.com"}

Use Get-DistributionGroup to validate the change:

Get-DistributionGroup |fl PrimarySmtpAddress,EmailAddresses

Use Set-DistributionGroup to set the DL’s PrimarySmtpAddress with a domain value of hazem.exohybridlabs.com:

Set-DistributionGroup DemoDl -PrimarySmtpAddress "DemoDl@hazem.exohybridlabs.com" -WindowsEmailAddress "DemoDL@hazem.exohybridlabs.com"

Optionally use Set-DistributionGroup to remove the DL’s secondary alias (if added):

Set-DistributionGroup DemoDl -EmailAddresses @{remove="DemoDl@anotheraccepteddomain.com"}

After making these changes, the DL upgrade will now succeed.

In this next example, we are trying to upgrade DemoDL3. The DL didn’t upgrade, and an ambiguous error is reported. Using the tool, we can see the blocker that prevented the upgrade from succeeding.

The blocker is that unsupported DL owners were found. If a DL owner has RecipientTypeDetails other than UserMailbox or MailUser (as stated here), the upgrade will fail.

To remove this blocker, use the steps below to remove all unsupported owners:

1.      Connect to Exchange Online PowerShell.
2.      Use Get-DistributionGroup to retrieve the list of DL owners and use Set-DistributionGroup to replace the recipient types:

$dl=Get-DistributionGroup DemoDL3@hazem.exohybridlabs.com
$dl.ManagedBy
Set-DistributionGroup -Identity “DemoDL3@hazem.exohybridlabs.com” -ManagedBy “<OwnerName(s)>”

After making these changes, the DL upgrade will now succeed.

Special thanks to Bhalchandra Atre, Nino Bilic who reviewed and contributed to this post.

Hazem Embaby
Support Escalation Engineer