Lesson 30 — Microsoft Entra Cloud Sync Troubleshooting

Learning objectives

After completing this lesson, you should be able to investigate Microsoft Entra Cloud Sync problems methodically and restore synchronisation without relying on trial and error.

• Define the major Cloud Sync troubleshooting boundaries.
• Validate provisioning agent and agent-pool health.
• Investigate service, registration and connectivity failures.
• Use Provisioning Logs to isolate object-level problems.
• Diagnose scope, matching and attribute-mapping issues.
• Recognise quarantine, retry and stalled-processing patterns.
• Separate single-object failures from configuration-wide outages.
• Build a safe recovery and verification workflow.

The problem this solves

Cloud Sync incidents rarely present as one clear failure. An agent may appear active while one configuration is unhealthy, one organisational unit is excluded or a target object is blocked by a duplicate value.

A structured workflow prevents unnecessary agent reinstalls, broad scope changes and repeated restarts that hide the original evidence.

Start with the symptom

Write down exactly what is wrong before changing anything. The troubleshooting path for one missing user differs from the path for an entire configuration that has stopped processing.

• One object missing
• One attribute stale
• Many objects failing
• No recent provisioning activity
• Duplicate objects created
• Configuration in quarantine

Establish the blast radius

Determine whether the issue affects one identity, one organisational unit, one agent, one configuration or every Cloud Sync workflow.

The blast radius is one of the strongest clues to the failure boundary.

Agent health

Confirm that each provisioning agent is installed, registered and reporting as expected. A healthy agent pool should not depend on a single server.

Check whether the agent service is running, whether the server was recently restarted and whether security software or patching changed local behaviour.

Agent pool resilience

Multiple agents provide resilience only when they are independently healthy and able to reach the required services.

Two agents behind the same failed proxy or network path do not provide meaningful redundancy.

Connectivity failures

The provisioning agent requires outbound connectivity to Microsoft cloud services and reliable access to the source Active Directory environment.

Proxy authentication, TLS inspection, DNS, firewall rules and service-account restrictions can interrupt processing even when the server remains online.

Connectivity questions

• Can the agent resolve required endpoints?
• Can it establish outbound HTTPS sessions?
• Was a proxy, firewall or inspection policy changed?
• Can it reach the required domain controllers?
• Are certificates and system time valid?
• Is the same failure present on every agent?

Provisioning Logs

Provisioning Logs remain the primary source for object-level Cloud Sync evidence. Search by identity, status, action, job and time range.

Read the detailed record, not only the summary row. The skip reason, processing step, source and target identifiers and modified properties usually reveal the next action.

Group failures by pattern

Do not investigate hundreds of events individually when they share the same error.

Group by job, status, error code, time and affected object type to identify whether the root cause is common.

Scope problems

Cloud Sync can operate normally while expected users remain absent because they are outside the configured organisational units, groups or attribute filters.

Always compare the object's current source placement with the intended scope.

Scope checks

• Correct organisational unit
• Required group membership
• Expected attribute-filter values
• Configuration enabled and assigned
• No exclusion rule taking precedence
• Source object visible to the agent

Object matching failures

Cloud Sync must identify whether a source object should join an existing cloud identity or create a new one.

Non-unique or inconsistent matching values can cause duplicate objects, incorrect joins or provisioning failures.

Matching evidence

• Source object ID
• Target object ID
• User principal name
• Mail and proxy addresses
• Matching attribute values
• Soft-deleted or conflicting targets

Attribute-mapping failures

A user may be created successfully while one or more attributes remain missing, invalid or stale.

Review the source value, mapping or transformation, value sent to the target and the target response.

Common mapping issues

• Required source value is empty
• Invalid format or excessive length
• Transformation produces an unexpected result
• Attribute is not included in the mapping
• Target value conflicts with another object
• Source authority is misunderstood

Quarantine

A provisioning configuration can enter quarantine when persistent failures make continued normal processing unsafe or ineffective.

Quarantine is a protective state and a symptom of an unresolved root cause—not the root cause itself.

Quarantine mistakes

• Restarting without reading repeated errors
• Assuming the agent itself is broken
• Clearing the state before correcting the cause
• Ignoring the percentage of failed objects
• Making broad scope changes during recovery

Configuration-wide failures

When many objects fail at the same time, prioritise shared dependencies: credentials, permissions, agent connectivity, target availability, mapping changes and configuration scope.

A sudden common start time often points to a recent administrative or infrastructure change.

Single-object failures

When other users continue to synchronise, focus on the affected source object, scope eligibility, unique values, matching and attribute quality.

Do not reinstall agents to solve a problem isolated to one identity.

Common mistakes

• Reinstalling agents before checking object-level logs.
• Assuming active means fully healthy.
• Ignoring skipped events.
• Changing multiple settings at once.
• Clearing quarantine without correcting the cause.
• Testing recovery with the entire directory.
• Closing the incident before verifying target objects.

Best practices

• Maintain at least two independently healthy agents.
• Baseline normal event and failure volumes.
• Keep scope narrow and documented.
• Use stable, unique matching attributes.
• Validate mapping changes with test objects.
• Capture identifiers and timestamps for every incident.
• Document root cause, correction and verification.