Directory synchronization fails in two very different ways: an object is exported to Microsoft Entra ID and rejected with an error, or it never leaves the Entra Connect server at all. In this post I'll go through the export errors Microsoft documents, explain the hard-match and soft-match logic behind most of them, and show how to track down an object that simply never appears in the cloud.
Symptoms#
You get the directory synchronization error email, the Microsoft 365 admin center flags a sync problem, or a user tells you their account or new email address isn't in Entra ID. In Synchronization Service Manager the Entra connector's export run shows a status such as completed-export-errors, and the object lists one of the errors below.
| Error | Meaning |
|---|---|
AttributeValueMustBeUnique | The object would receive a value of mail, proxyAddresses, signInName or userPrincipalName that another Entra object already holds. |
InvalidSoftMatch | No hard match was found, the soft match found an object, but that object already has a different immutableId, so it belongs to another on-premises object. |
ObjectTypeMismatch | The soft match found an object of a different type (for example a mail-enabled group with the same SMTP address as a new user). |
InvalidHardMatch | Entra ID blocked a hard match because the target cloud user is privileged (assigned or eligible for a privileged role) or already mapped to an on-premises object. Enforced automatically since July 1, 2026. |
IdentityDataValidationFailed / DataValidationFailed | Invalid data, typically unsupported characters or a bad format in the UPN. |
LargeObject / ExceededAllowedLength | The object exceeds the size limit, usually because of userCertificate, userSMIMECertificate, thumbnailPhoto or a very long proxyAddresses list. |
| Existing Admin Role Conflict | An on-premises user has the same UPN as a cloud user that holds an admin role; soft matching to admin accounts isn't allowed. |
Why it happens#
When Entra Connect adds a new object, Entra ID first tries a hard match on the sourceAnchor, which is the Base64 form of the user's ms-DS-ConsistencyGuid (or objectGUID in older configurations) and is stored in the cloud as ImmutableId. If nothing matches, it tries a soft match on the userPrincipalName or the primary SMTP address, meaning only the SMTP: entry in proxyAddresses. A successful match converts the cloud object to on-premises managed and overwrites its attributes with the on-premises values. Matching is only attempted for new objects; if you later change an existing object so that it collides with another, you get an error instead.
Most duplicate errors are therefore one of three stories: two Active Directory objects share an address or UPN, an object was recreated (or moved between forests) so its sourceAnchor changed while the old cloud object still exists, or a cloud-created object collides with a newly synced one. Duplicate attribute resiliency quarantines a conflicting proxyAddresses or UPN value instead of failing the whole object, but the data still has to be fixed. Objects that never sync are usually caught by domain or OU filtering, by the default scoping rules (anything with isCriticalSystemObject set to TRUE, such as Domain Admins, is excluded by design), or by a custom attribute filter that sets cloudFiltered to True.
How to fix it#
1. Find the error details#
The quickest view is the sync error report in Microsoft Entra Connect Health › Sync services. It needs the Connect Health agent on the sync server, refreshes every 30 minutes after each export, groups errors into categories (Duplicate Attribute, Data Mismatch, Data Validation Failure, Federated Domain Change, Large Attribute, Other), shows the conflicting objects side by side and exports to CSV; supported duplicate-attribute cases offer a guided Fix this error action. Without Connect Health, open Synchronization Service Manager, select the failed run on the Operations tab and follow the object link under Synchronization Errors to the Stack Trace.
2. Resolve duplicate values#
For AttributeValueMustBeUnique, InvalidSoftMatch and ObjectTypeMismatch, decide which object should keep the value, remove it from the other one in its source directory, and let the next delta cycle export the change. Run IdFix against Active Directory to find every duplicate, blank or malformed value in one pass instead of chasing them one at a time.
3. Make the right object match#
When the new on-premises object should take over an existing cloud user (a recreated account, a forest move, or a reinstalled Entra Connect with a different anchor), force a hard match by writing the cloud ImmutableId into the user's ms-DS-ConsistencyGuid:
Connect-MgGraph -Scopes "User.Read.All"
$cloudUser = Get-MgUser -UserId "bob.taylor@contoso.com" -Property OnPremisesImmutableId
$guid = [Guid][Convert]::FromBase64String($cloudUser.OnPremisesImmutableId)
Set-ADUser -Identity bobt -Replace @{ 'mS-DS-ConsistencyGuid' = $guid.ToByteArray() }
Start-ADSyncSyncCycle -PolicyType DeltaIf the target holds an admin role, or is eligible for one, remove the role first, hard-delete the quarantined object that Entra Connect created in the cloud, sync, then restore the role. A cloud user whose onPremisesObjectIdentifier is already set must have it cleared to null (through Microsoft Graph or the ADSyncTools module) before the match is allowed. Check the tenant's matching switches with the Microsoft Graph PowerShell SDK:
Connect-MgGraph -Scopes "OnPremDirectorySynchronization.Read.All"
Get-MgDirectoryOnPremiseSynchronization | Select-Object -ExpandProperty Features | Format-ListBlockSoftMatchEnabled and BlockCloudObjectTakeoverThroughHardMatchEnabled are protections Microsoft recommends leaving on; disable them only for the duration of a planned takeover, with Update-MgDirectoryOnPremiseSynchronization.
4. Fix data validation and size errors#
Correct UPNs with unsupported characters or formats (IdFix flags them), and verify the UPN suffix as a domain in the tenant, otherwise the user lands on the onmicrosoft.com domain. For LargeObject, clear expired certificates from userCertificate and userSMIMECertificate (the hard limit is 15), shrink the photo, and delete stale X.400, X.500, MSMail or CcMail addresses; Microsoft suggests treating roughly 300 proxy addresses as the practical ceiling.
5. Find an object that never syncs#
- On the Entra Connect server, start the wizard and go to Additional Tasks › Troubleshoot › Launch, then choose Troubleshoot Object Synchronization. Give it the object's distinguished name, the AD connector name and Hybrid Identity Administrator credentials. It checks UPN mismatch, domain and OU filtering, linked mailboxes and dynamic distribution groups, and writes an HTML report.
- Manually, open Synchronization Service Manager, select Connectors, the Active Directory connector and Search Connector Space. If the object is missing, it's outside domain or OU filtering: rerun the wizard and re-select the OU (a renamed OU drops out of scope silently).
- If the object is in the connector space but Metaverse Search doesn't find it, a scoping filter stopped it. In the Synchronization Rules Editor, compare the inbound rules' scoping filters with the object's attributes;
isCriticalSystemObjectand custom attribute filters are the usual culprits. - If it's in the metaverse but not in the Entra connector space, check the outbound rule scope and whether
cloudFilteredis True.
6. Run the right sync cycle#
Delta syncs run every 30 minutes by default. Changing OU filtering needs a full import followed by a delta sync; changing attribute filtering needs a full synchronization. The simplest supported route is to put the server in staging mode and run:
Get-ADSyncScheduler
Start-ADSyncSyncCycle -PolicyType Initial # full import + full sync on all connectors
Start-ADSyncSyncCycle -PolicyType DeltaUse Set-ADSyncScheduler -SyncCycleEnabled $false while you edit rules, and remember that prevent accidental deletes stops the export if more than 500 deletions are pending.
Verify the fix#
- After the next export (and up to 30 minutes for Connect Health to refresh), the object no longer appears in the error report and the Operations tab shows
successfor the Entra connector. - In Entra ID › Users, the user shows On-premises sync enabled: Yes with the expected UPN and addresses, and the metaverse object lists both the Active Directory and Entra connectors on its Connectors tab.
- For a forced hard match, confirm the cloud user kept its licences, mailbox and group memberships.
Prevent it next time#
- Clean Active Directory with IdFix before onboarding new domains, and keep
ms-DS-ConsistencyGuidas the source anchor so account recreations don't orphan cloud objects. - Don't create cloud-only users for people who exist in Active Directory; let synchronization create them.
- Install the Connect Health agent and watch the error report and alerts rather than waiting for the notification email.
- Consider Microsoft Entra Cloud Sync for new environments: lightweight provisioning agents, configuration stored in the cloud, multiple agents for high availability and support for disconnected forests. It's Microsoft's strategic direction for hybrid synchronization, but compare the feature list first, because not every Connect Sync capability is available yet.