Microsoft Entra Connect (formerly Azure AD Connect) keeps on-prem Active Directory and Entra ID in step. When it breaks, it rarely breaks loudly. A user's new title doesn't show up, a new hire can't sign in, or a notification email about sync errors gets filtered as noise. Here's how to find the problem and fix it.
Where errors show up
- Microsoft 365 admin center -> Health -> Directory sync status: a quick view of last sync and object errors
- Entra admin center -> Entra Connect -> Connect Sync: sync status plus Entra Connect Health, if its agent is installed
- On the sync server: the Synchronization Service Manager (
miisclient.exe) shows every run and every error, per object - Email notifications to the technical contact on the tenant. Make sure that goes to a mailbox someone reads.
Check the sync engine first
On the Entra Connect server:
Import-Module ADSync
Get-ADSyncScheduler # SyncCycleEnabled should be True, and NextSyncCycleStartTimeInUTC recent
Get-ADSyncConnectorRunStatus # shows whether a sync run is in progress
# Run a delta sync after fixing an object
Start-ADSyncSyncCycle -PolicyType DeltaIf SyncCycleEnabled is False, someone paused it, often during a previous troubleshooting session, and never turned it back on:
Set-ADSyncScheduler -SyncCycleEnabled $trueThe common errors
| Error | What it means | Fix |
|---|---|---|
| AttributeValueMustBeUnique | Two objects share a proxyAddresses or userPrincipalName value | Find the duplicate (often an old contact or a cloud-only user) and remove the conflicting value |
| InvalidSoftMatch | Entra Connect tried to match an on-prem user to an existing cloud user, but the cloud user was already linked to a different object | Check both objects' source anchors. Don't delete the cloud user without knowing what's attached to it. |
| ObjectTypeMismatch | An on-prem object tried to match a cloud object of a different type (a contact vs. a user) | Remove or rename one of them |
| LargeObject / ExceededAllowedLength | Too many values on an attribute, often userCertificate or proxyAddresses | Clean up stale certificates or addresses on the on-prem object |
| DataValidationFailed | An invalid value, such as a UPN with an unroutable suffix or illegal characters | Fix the attribute in AD; IdFix finds these in bulk |
Find the object with a duplicate proxy address quickly:
# On-prem
Get-ADObject -LDAPFilter "(proxyAddresses=smtp:alex@yourcompany.com)" -Properties proxyAddresses
# Cloud side (Exchange Online)
Connect-ExchangeOnline
Get-Recipient -Filter "EmailAddresses -eq 'smtp:alex@yourcompany.com'" | Format-Table Name, RecipientTypePassword hash sync issues
If users sign in on-prem with a new password but the cloud still wants the old one:
- Confirm password hash sync is enabled in the Entra Connect wizard.
- Look in the server's Application event log for password sync events (source Directory Synchronization).
- A full password sync can be triggered from the wizard, but try a delta sync and a few minutes' patience first.
Keep Entra Connect current
Microsoft retires old Entra Connect builds on a schedule, and retired versions eventually stop syncing. Check the version you're running against Microsoft's version history page, enable auto-upgrade where it's supported, and plan manual upgrades for the rest.
When sync keeps breaking
Recurring sync errors usually point to a bigger issue: AD that's never been cleaned up, users being created in both places, or a sync scope nobody documented. If AD mostly exists to feed Microsoft 365, it may be time to ask whether you still need it at all.