title: Troubleshooting Sync Errors category: Troubleshooting tags: troubleshooting, sync, errors, ldap, timeout, mapping priority: Normal

Troubleshooting Sync Errors

This guide covers the most common synchronization errors in IdentityCenter, their root causes, and step-by-step solutions. Sync errors can originate from LDAP queries, attribute mappings, network conditions, or database constraints.

LDAP Query Errors

Invalid Filter Syntax

Symptoms:

• Sync fails immediately with "Invalid LDAP filter" error
• No objects returned despite valid connection

Common Causes and Fixes:

Tip: IdentityCenter uses objectCategory in its default filters for better performance. For example, the default user filter is (&(objectClass=user)(objectCategory=person)). Always test your custom filters with a small scope first.

Access Denied

Symptoms:

• Sync returns "Insufficient access rights" or "Access is denied"
• Partial results returned (some OUs accessible, others not)

Solutions:

1. Verify the service account has Read permissions on all target OUs
2. Check that the account has List Contents permission on parent containers
3. For cross-domain queries, ensure the account has permissions in the target domain
4. In Active Directory Users and Computers, right-click the OU, select Properties > Security, and confirm the service account is listed with Read access

Search Size Limit Exceeded

Symptoms:

• Error: "Size limit exceeded" or "SizeLimitExceeded"
• Only partial results returned (typically 1000 objects)

Solutions:

1. Enable paging -- IdentityCenter's DirectoryQueryService uses paged search by default with a page size of 1000. Verify paging is enabled in your connection settings.
2. Reduce scope -- Target specific OUs rather than the entire directory root.
3. Check Active Directory policies -- The MaxPageSize LDAP policy on your domain controller defaults to 1000. Verify with:

   ntdsutil "LDAP policies" connections "connect to server DC01" quit "show values" quit quit
   

Referral Chasing Issues

Symptoms:

• Error: "A referral was returned from the server"
• Objects in child domains or other partitions are not returned

Solutions:

1. Point the connection directly at the target domain controller rather than relying on referrals
2. Use Global Catalog (port 3268/3269) for cross-domain queries
3. Check that DNS resolution works for all domain controllers in the referral chain

Timeout Errors

Large OU Timeouts

Symptoms:

• Sync starts but fails with "The operation has timed out"
• Works for small OUs but fails for large ones

Solutions:

1. Increase the LDAP query timeout in the connection configuration
2. Reduce the attribute list -- Only request attributes you actually need in your attribute mappings
3. Split large OUs -- Create multiple sync steps targeting child OUs instead of one large parent
4. Check network latency -- Run Test-Connection from the IdentityCenter server to the domain controller

Slow Network Conditions

If syncs fail intermittently due to network instability:

1. Ensure the IdentityCenter server is on the same site or subnet as the domain controller
2. Verify no packet loss: Test-Connection -ComputerName dc01.corp.local -Count 20
3. Consider using a domain controller in the same data center
4. Reduce the LDAP page size from the default 1000 to 500 to decrease per-request payload

Attribute Mapping Failures

Attribute Does Not Exist in Schema

Symptoms:

• Error: "Attribute not found in schema" or empty values for all objects
• Other attributes sync correctly

Solutions:

1. Verify the attribute name is spelled correctly (attribute names are case-insensitive but must be exact)
2. Check if the attribute is part of a schema extension that may not be present in your forest
3. Use ADSI Edit or PowerShell to confirm the attribute exists:

   Get-ADObject -SearchBase (Get-ADRootDSE).schemaNamingContext `
     -Filter "lDAPDisplayName -eq 'customAttribute'" -Properties *
   

Type Mismatch Errors

Symptoms:

• Error referencing data type conversion failure
• Sync completes but mapped values are incorrect or null

Common Mismatches:

Null Value Handling

When source attributes are empty or null:

1. Check the mapping's null behavior -- Configure whether to skip, set a default, or clear the target field
2. Required fields -- If the target column is NOT NULL in the database, provide a default value in the mapping
3. Conditional mappings -- Use expressions to provide fallback values when the primary attribute is empty

Object Count Mismatches

When the sync reports fewer objects than expected:

Objects Filtered by LDAP Query

1. Review your LDAP filter -- It may exclude objects unintentionally
2. Disabled accounts may be filtered out if your filter includes (!(userAccountControl:1.2.840.113556.1.4.803:=2))
3. Objects in child OUs may not be included if search scope is set to One Level instead of Subtree

Objects Deleted in AD but Cached Locally

1. IdentityCenter tracks objects by their SourceUniqueId (objectGUID). If an object is deleted in AD and recreated, it gets a new GUID.
2. Check the sync project's deleted object handling setting -- Objects removed from AD can be marked as inactive or deleted locally.
3. Review the Objects page at /admin/directory/objects and filter by IsActive to see which objects the system considers current.

Sync Stuck in Running State

Symptoms:

• Sync project shows "Running" status for an extended period
• No progress updates in the sync run log

Solutions:

1. Navigate to Processing Center at /admin/processing-center to view active jobs
2. Check if the job is actively processing or if it has stalled
3. If stalled, cancel the job from Processing Center and investigate the logs before restarting
4. Check the application logs at /admin/logging for errors that occurred during the stuck run
5. Verify the domain controller is responsive -- a network interruption during sync can leave it in a running state

Important: Do not start a new sync run while the previous one is stuck. Cancel the stuck run first to avoid duplicate processing.

Duplicate Object Errors

Unique Constraint Violations

Symptoms:

• Error: "Violation of UNIQUE KEY constraint" on (SourceConnectionId, SourceUniqueId)
• Objects fail to insert during bulk upsert

Causes and Solutions:

1. Same object imported from two connections -- Each connection has its own SourceConnectionId. If you have two connections pointing to the same domain controller, the same object may be imported twice with different connection IDs. Consolidate to a single connection per domain.
2. objectGUID collision -- Extremely rare in production. Verify with:

   Get-ADUser -Filter * -Properties objectGUID | Group-Object objectGUID | Where-Object { $_.Count -gt 1 }
   

3. Stale data from previous imports -- If you changed the Base DN of a sync step, old objects from the previous scope may conflict. Review and clean up stale records.

The SyncObjectRepository.FastBulkUpsertObjectsAsync method uses a HashSet and MERGE strategy to handle duplicates efficiently. In most cases, duplicates are automatically resolved by the upsert logic. Persistent errors indicate a data quality issue that should be investigated.

Reading Sync Run Logs

Navigate to /admin/sync-project-runs to view detailed run history:

Tips for log analysis:

• Click a run to view step-by-step details and per-object error messages
• Filter by Failed status to focus on problem runs
• Compare successful and failed runs to identify what changed
• Export run details when opening a support ticket

When to Re-Run vs. Investigate

Escalation: When to Contact Support

Contact support at support@certification-center.com if:

• The same error persists after following all troubleshooting steps above
• You see database-level errors (deadlocks, corruption warnings)
• The application crashes during sync operations
• You need help interpreting complex error messages in the logs

When contacting support, include:

1. The sync run ID and timestamps
2. Exported sync run logs
3. Application logs from /admin/logging covering the failure window
4. Your IdentityCenter version number
5. A description of any recent changes (new mappings, connection changes, AD changes)

Next Steps

• Troubleshooting Connection Issues
• Performance Tuning
• Log Analysis & Diagnostics
• Sync Configuration Guide
• Common Issues & Solutions