title: Sync Troubleshooting Guide category: Synchronization tags: sync, troubleshooting, errors, failed, diagnostics priority: Normal

Sync Troubleshooting Guide

When a synchronization project fails or produces unexpected results, this guide helps you diagnose the issue and apply the correct fix. Start with the diagnostic workflow, then find your specific problem in the reference sections below.

Diagnostic Workflow

Follow these steps in order when investigating a sync issue:

1. Check the Sync Run Details page at Synchronization > Sync Project Runs -- this shows the status, duration, and error messages for each run
2. Review the step-by-step breakdown -- each sync step (Query, Transform, Lookup, Upsert, Membership, Cleanup) reports its own status
3. Check the Items Processed / Succeeded / Failed counters -- these tell you exactly how many objects were affected
4. Look at the error messages and categories -- the run details include categorized errors with descriptions
5. Verify the underlying connection -- a sync failure is often caused by a connection problem

Common Sync Issues

Sync Stuck at "Running"

Symptom: A sync project shows "Running" status for an unusually long time and never completes.

Possible causes:

• The LDAP query is taking longer than expected (very large scope, slow DC)
• The database server is under heavy load
• The IdentityCenter process experienced an unhandled error that prevented status update
• Another sync job is holding a resource lock

Fix:

1. Check the Processing Center for active and queued jobs
2. If the job appears stalled, restart the IdentityCenter service -- the job will be marked as failed on restart
3. Review the application logs for unhandled exceptions during the stuck period
4. If the issue recurs, reduce the sync scope (fewer OUs) or increase timeout settings

0 Objects Synced

Symptom: The sync completes successfully but reports 0 items processed.

Possible causes:

• The LDAP filter is returning no results
• The search scope is set to Base instead of Subtree
• The Base DN points to an empty OU
• The service account does not have read permissions on the target OU

Fix:

1. Verify the LDAP filter syntax. Common correct filters:

2. Check the search scope is set to Subtree (not Base or OneLevel, unless intentional)
3. Verify the Base DN is correct and contains objects
4. Test the connection to confirm the service account can read the target OUs
5. Try running the LDAP query manually using ldp.exe or PowerShell to confirm results are returned

Objects Missing After Sync

Symptom: Some objects you expect to see are not in IdentityCenter after a sync completes.

Possible causes:

• The LDAP filter is too restrictive and excludes those objects
• The search scope is OneLevel and the objects are in nested OUs
• The objects were created or moved after the sync started (timing issue)
• The objects are in a different domain or forest

Fix:

1. Review the LDAP filter for unintended exclusions (e.g., filtering out disabled accounts)
2. Change the search scope to Subtree to include nested OUs
3. Check if the objects exist in the directory by querying with a broader filter
4. If the objects are in a different domain, verify that the correct connection and Base DN are configured

Duplicate Objects

Symptom: The same real-world entity appears multiple times in the Objects list.

Possible causes:

• The object is being synced from multiple connections (e.g., both a direct DC connection and a Global Catalog connection)
• The unique constraint on (SourceConnectionId, SourceUniqueId) prevents true duplicates within a single connection, but objects from different connections are stored separately by design

Fix:

1. Check if the duplicates come from different SourceConnectionId values -- if so, this is expected behavior for multi-source environments
2. If you have overlapping connections (e.g., a domain connection and a GC connection that covers the same domain), remove the redundant connection or adjust the LDAP filters to avoid overlap
3. The Person matching engine should link these objects to the same Person record; verify that matching is working correctly

Attribute Values Not Updating

Symptom: An attribute that changed in Active Directory is not reflected in IdentityCenter after sync.

Possible causes:

• The attribute is not included in the sync project's attribute mappings
• A transform mapping is overriding or discarding the new value
• The delta sync did not detect the change (possible if whenChanged did not update for that attribute)
• Multi-valued attribute handling may not process all values

Fix:

1. Open the sync project and check the Attribute Mappings tab -- confirm the attribute is mapped
2. If using a transform mapping, verify the transform logic handles the new value correctly
3. Run a full sync instead of delta to force a complete comparison
4. For multi-valued attributes (like proxyAddresses), verify the attribute is being processed correctly

Manager Resolution Failing

Symptom: Users show no manager or "Unresolved" manager even though the manager attribute is populated in AD.

Possible causes:

• The manager object has not been synced yet
• The manager is in a different OU that is not included in the sync scope
• The manager's DN changed (rename or move) and the old DN no longer matches
• The manager is in a different forest (see Multi-Forest Setup)
• Circular manager references

Fix:

1. Verify the manager object exists in IdentityCenter's Objects list
2. If the manager is in a different OU, expand the sync scope or create a separate sync project for that OU
3. Run a full sync to refresh all DN references
4. For cross-forest managers, ensure both forests are connected and synced
5. See Manager Resolution for detailed troubleshooting

Membership Sync Incomplete

Symptom: Group members are missing, or group membership counts do not match AD.

Possible causes:

• Very large groups (5,000+ members) require AD's range retrieval mechanism
• The Membership sync step timed out before completing
• Some member objects have not been synced yet
• The group's member attribute uses linked values that require paged retrieval

Fix:

1. Check if the affected groups are very large (5,000+ members) -- IdentityCenter handles range retrieval automatically, but verify it is working
2. Increase the timeout for the Membership sync step if groups are exceptionally large
3. Ensure all member objects have been synced before running the Membership step (order your sync projects: users first, then groups)
4. Run a full sync on the group sync project

Performance Degradation

Symptom: Sync runs are taking significantly longer than they used to.

Possible causes:

• The number of objects in scope has grown
• Too many attributes are mapped (especially large or binary attributes)
• Overlapping sync schedules cause resource contention
• The SQL Server database needs index maintenance
• A change in network conditions (latency, bandwidth)

Fix:

1. Review attribute mappings and remove any that are unnecessary (see Custom Attribute Mapping)
2. Stagger sync schedules so that large projects do not run simultaneously
3. Run SQL Server index maintenance:

   -- Check index fragmentation
   SELECT OBJECT_NAME(ips.object_id) AS TableName,
          i.name AS IndexName,
          ips.avg_fragmentation_in_percent
   FROM sys.dm_db_index_physical_stats(DB_ID(), NULL, NULL, NULL, 'LIMITED') ips
   JOIN sys.indexes i ON ips.object_id = i.object_id AND ips.index_id = i.index_id
   WHERE ips.avg_fragmentation_in_percent > 30
   ORDER BY ips.avg_fragmentation_in_percent DESC;
   

4. Consider switching from full sync to delta sync for routine runs (see Delta & Incremental Sync)
5. Check DC responsiveness -- if LDAP queries are slow, the issue may be on the DC side

Reading Sync Run Logs

The Sync Project Runs page provides detailed information for each run:

Understanding Items Processed vs. Succeeded vs. Failed

• Items Processed = total objects the sync engine attempted to handle
• Items Succeeded = objects that were created, updated, or confirmed unchanged
• Items Failed = objects that encountered an error during processing

A healthy sync run has Items Failed = 0. If failures occur, expand the error details to see which objects failed and why.

Error Categories

Sync errors are grouped into categories for easier diagnosis:

When to Re-Run vs. Investigate

Escalation Path

If you cannot resolve the issue using this guide:

1. Collect logs -- Export the sync run details and application logs
2. Document the timeline -- When did the issue start? What changed?
3. Check System Center -- Look for related warnings or errors
4. Review recent changes -- Were connections, mappings, or schedules modified?
5. Contact support with the collected information

Next Steps

• Connection Troubleshooting -- Resolve underlying connection issues
• Custom Attribute Mapping -- Fix mapping-related sync problems
• Delta & Incremental Sync -- Switch to delta sync for better performance
• Scheduling Sync -- Optimize your sync schedule
• System Requirements -- Verify your infrastructure meets requirements