Entra Connect Identity Sync Pitfalls That Stall Mail Migrations

Every hybrid migration runs on top of directory synchronization. Entra Connect, still called Azure AD Connect in a lot of documentation and in the installer's old name, copies users, groups and Exchange attributes from Active Directory to Entra ID. When it is set up carefully the migration barely notices it. When it is not, mailbox moves fail with errors that mention GUIDs and nothing about the real cause.

This post lists the sync problems that most often stall a migration, how to spot them before the first batch, and how to fix each one.

UPN suffixes and the .local problem

Users sign in to Microsoft 365 with their user principal name. If your Active Directory domain is company.local, every UPN ends in .local, which cannot be verified in Entra ID, so the synced users get an onmicrosoft.com sign-in name instead. Users then have to remember a different address for sign-in than for email, and Autodiscover and ZeroConfigExchange stop matching.

Fix it before sync. Add the public domain as a UPN suffix in Active Directory Domains and Trusts, then change every user's UPN to match their primary email address. Run this in a test OU first, since a few applications key on the UPN.

Get-ADUser -Filter { UserPrincipalName -like "*.local" } -Properties mail | Select SamAccountName, UserPrincipalName, mail
Get-ADUser -Filter { UserPrincipalName -like "*.local" } -Properties mail | Where-Object { $_.mail } | ForEach-Object { Set-ADUser $_ -UserPrincipalName $_.mail }

Attribute cleanup with IdFix

Entra ID rejects objects with invalid characters, duplicate proxy addresses, or a mail attribute that collides with another object. Each rejected object is one user who will not sync and one mailbox that cannot move. Microsoft's IdFix tool scans the directory and lists every problem with a suggested fix.

Run it before installing Connect, fix everything it flags, and run it again. The usual finds are trailing spaces in mail attributes, two users sharing an SMTP alias from an old rename, and contacts that duplicate a user's address.

Get-ADObject -Filter { proxyAddresses -like "*" } -Properties proxyAddresses | ForEach-Object { $o=$_; $_.proxyAddresses | ForEach-Object { [pscustomobject]@{ Object=$o.Name; Address=$_ } } } | Group-Object Address | Where-Object Count -gt 1 | Select Name, Count

Soft match, hard match and cloud-first accounts

If users were created in the cloud before sync was turned on, Connect has to match them to the on-prem accounts rather than create duplicates. Soft match works on the primary SMTP address or the UPN. It succeeds when the addresses are identical and fails quietly when they are not, leaving you with a second user named jsmith2 and a mailbox move that reports the target already has a mailbox.

Hard match sets the cloud user's immutable ID to the on-prem source anchor by hand, which forces the link. It is the fix when soft match cannot see the connection. The source anchor should be ms-DS-ConsistencyGuid, which Connect chooses by default on current versions.

The bigger trap is a cloud user who already has an Exchange Online mailbox with data in it. Sync will match the accounts, but the hybrid move cannot overwrite the existing cloud mailbox. Those users need the cloud mailbox removed or exported before the on-prem mailbox is moved.

$guid = (Get-ADUser jsmith).ObjectGUID
$immutable = [Convert]::ToBase64String($guid.ToByteArray())
Connect-MgGraph -Scopes "User.ReadWrite.All"
Update-MgUser -UserId jsmith@domain.com -OnPremisesImmutableId $immutable

Exchange hybrid writeback and the attributes that matter

The Connect installer has an optional feature called Exchange hybrid deployment. It writes a small set of attributes from Entra ID back to Active Directory, and, more importantly for migration, it syncs the on-prem mailbox GUID and other Exchange attributes up so that Exchange Online knows the cloud object is a mail user with an on-prem mailbox. If the option is off, the cloud object lacks the GUID, and the move fails at the start with an error about the mailbox GUID not matching.

Enable the option, run a full sync, and confirm the attributes arrived before you create a batch. Also check OU filtering: a user in an OU that is not synced simply does not exist in the cloud, which is obvious for people and less obvious for shared mailboxes and rooms that live in an OU nobody thought of.

Start-ADSyncSyncCycle -PolicyType Initial
Get-ADSyncScheduler
Get-ADSyncConnectorRunStatus

Connect-ExchangeOnline
Get-MailUser jsmith@domain.com | Format-List ExchangeGuid, ArchiveGuid, LegacyExchangeDN, EmailAddresses
Get-Mailbox jsmith -ErrorAction SilentlyContinue

Operational pitfalls

Connect is a single point of failure that nobody monitors. Install it on a member server, not a domain controller if you can avoid it, and keep the version current, since Microsoft retires old builds and stops accepting sync from them. Set up a second server in staging mode if the migration will run for months. Watch the Entra ID Connect Health blade or at least the event log for export errors.

Password hash sync is the simplest sign-in option and should stay on even with federation as a backup. Do not run two Connect servers in active mode against the same tenant, and do not rebuild the server without exporting the configuration first.

Frequently asked questions

Takeaway

Fix UPNs, run IdFix, turn on Exchange hybrid writeback, and confirm the Exchange GUID on a synced mail user before you create the first migration batch. Most of the identity errors during a hybrid move are one of those four things, and each takes far longer to unpick after the fact than to check up front.