Operations and Troubleshooting

Once Connect Sync is running, the day-to-day operational work is monitoring sync cycles, diagnosing errors when they surface, maintaining the staging server, and keeping the installation healthy through upgrades. This page covers the patterns operators need most.

Monitoring Sync Cycles

The Synchronization Service Manager

The Synchronization Service Manager (SSM) is the primary troubleshooting UI. Open it from the Start menu on the Connect server. It has four tabs:

• Operations - shows every import, sync, and export run with status, timestamps, and per-object details. This is where you start when something looks wrong.
• Connectors - lists configured connectors (AD forests, Entra ID). Right-click a connector to run operations, view statistics, or search its connector space.
• Metaverse Designer - shows the metaverse schema. Use this to verify custom attributes exist before referencing them in rules.
• Metaverse Search - lets you search for objects by attribute value and inspect their join status, contributing rules, and attribute lineage.

Reading the Operations Tab

Each operation row shows:

Click an operation to see:

• Statistics - total objects processed, errors, staging counts.
• Error details - per-object error messages with the object’s DN and error type.

PowerShell Monitoring

# Check scheduler state
Get-ADSyncScheduler

# View the last sync cycle result
Get-ADSyncConnectorRunStatus

# Manually trigger a delta sync
Start-ADSyncSyncCycle -PolicyType Delta

# Trigger a full sync (expensive, use only when needed)
Start-ADSyncSyncCycle -PolicyType Initial

Entra Connect Health

Microsoft Entra Connect Health provides cloud-side monitoring. It reports:

• Sync cycle history and latency.
• Object sync errors with remediation guidance.
• Alerts when the sync server stops reporting or when errors spike.

Check it in the Entra portal under Hybrid management > Microsoft Entra Connect > Connect Sync.

Common Error Patterns

Export Errors to Entra ID

These are the most frequent operational errors. They surface when the engine tries to write changes to Entra ID and the service rejects them.

InvalidSoftMatch

Cause: The engine tries to soft-match an on-premises object to an existing Entra object by proxyAddresses or userPrincipalName, but the Entra object already has a different immutableId (sourceAnchor). This usually means two on-premises objects conflict on the same UPN or email.

Fix: Identify the duplicate attribute value. Determine which object should own it. Remove the duplicate from the other object in AD, then let sync propagate the fix.

AttributeValueMustBeUnique

Cause: Two objects are trying to sync with the same value for userPrincipalName, proxyAddresses, mail, or signInName. Entra ID enforces uniqueness on these.

Fix: Same approach as InvalidSoftMatch - find the duplicate in AD and resolve it. The Connect Health sync error report identifies both objects.

LargeObject / ExceededAllowedLength

Cause: An object’s total attribute data exceeds the Entra ID size limit. Common culprits: too many userCertificate entries (hard limit: 15), too many proxyAddresses (practical limit: ~300), or an oversized thumbnailPhoto.

Fix: Clean up the offending attribute in AD. Remove expired certificates, prune unnecessary proxy addresses, or resize the thumbnail photo.

InvalidHardMatch

Cause: A hard match by sourceAnchor is blocked because:

• The BlockCloudObjectTakeoverThroughHardMatchEnabled feature is enabled.
• The target Entra object has privileged roles assigned.

Fix: For privileged user conflicts: restore the user, remove admin roles, complete the hard match, then reassign roles. For general cases, check if the blocking feature needs to be adjusted.

Existing Admin Role Conflict

Cause: A soft match is attempted against an Entra object that has administrative roles assigned. Entra blocks this to prevent account takeover.

Fix: Remove admin roles from the Entra account, hard-delete the quarantined object, let sync re-match, then reassign roles.

Import Errors

Less common but can indicate AD connectivity issues:

• Connectivity failure - the sync server cannot reach a domain controller. Check network, DNS, and firewall rules.
• Permission denied - the AD DS connector account lacks read access to an OU or attribute. Verify account permissions.
• Transient objects - usually benign. Appear when objects are moved or renamed in AD. Resolve automatically in subsequent delta sync cycles.

Staging Server Operations

Purpose

A staging server runs the full import/sync pipeline but never exports. It maintains a complete shadow copy of the sync state. Use it for:

• Disaster recovery - promote to active if the primary fails.
• Configuration testing - make rule changes, run sync, preview results without affecting production.
• Server replacement - prepare a new server, validate its output, then swap.

Promoting a Staging Server

To make a staging server active:

1. On the current active server: Re-run the Connect wizard and enable staging mode. This stops exports.
2. On the staging server: Re-run the Connect wizard and disable staging mode. This starts exports.
3. Verify: Check the Operations tab on the newly active server. Confirm exports are completing successfully.

Never run two active (non-staging) servers against the same Entra tenant. This causes data corruption and is not supported.

Verifying Staging Server State

Before promoting, verify the staging server is healthy:

1. Run full import and delta sync on all connectors.
2. Use csexport to dump the pending export for the Entra connector.
3. Compare the pending export against what you expect. Large discrepancies indicate configuration drift between the servers.

csexport "contoso.com - AAD" %temp%\export.xml /f:x
CSExportAnalyzer %temp%\export.xml > %temp%\export.csv

Review the CSV in Excel before promoting.

Health Check Patterns

Weekly Health Check

1. Review Connect Health alerts in the Entra portal. Address any active alerts.
2. Check sync error count in the Operations tab. A healthy server should have zero or near-zero persistent errors.
3. Verify the scheduler is running: Get-ADSyncScheduler should show SyncCycleEnabled = True.
4. Check disk space on the sync server. The SQL database grows with object count.
5. Review the event log (Application and ADSync logs) for warnings or errors.

After AD Changes

Whenever you make structural AD changes (new domains, OU renames, schema extensions, forest trust changes):

1. Re-run the Connect wizard to update connector configuration.
2. Run a full import on affected connectors.
3. Run a full sync to re-evaluate all objects.
4. Review pending exports before letting them go.

Upgrade Procedure

1. Install the staging server with the new version first.
2. Verify the staging server syncs correctly with the new version.
3. Promote the staging server to active.
4. Upgrade (or decommission) the old server.

This approach gives you a rollback path: if the new version has issues, you can re-promote the old server.

Operational Runbook Summary