# Fix onboarding agent timeout on Azure AD SCIM sync during user import

## TL;DR
The agent times out because Entra's SCIM sync runs on its own schedule and the agent waits with a short deadline. Poll the provisioning logs with a realistic timeout, or better, trigger on the sync completion event instead of polling. The sync is slow, not stuck.

## The error
```text
Onboarding agent timeout
Timed out waiting for Azure AD SCIM sync during user import.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=onboarding agent timeout on azure ad scim sync during user import"
```

## Fix it

### Step 1: Check the actual sync status in Entra

```bash
Open the provisioning logs for the import to see whether the sync is running, done, or failed.
```

Expected: You know the true state instead of guessing from the timeout.

### Step 2: Extend the agent's wait deadline

```bash
Set the poll timeout to cover a full sync cycle with margin.
```

Expected: The agent stops timing out on normal syncs.

### Step 3: Poll the logs, not the user list

```bash
Have the agent check provisioning log entries for completion rather than hammering the user API.
```

Expected: Polling is cheap and accurate.

### Step 4: Prefer events over polling where possible

```bash
If the platform offers sync completion signals, switch the agent to those.
```

Expected: No polling timeout to tune at all.

### Step 5: Verify the import completes

```bash
Re-run the import with the new wait strategy.
```

Expected: Users import fully within the deadline.

## When this applies

- Agents time out waiting on Entra SCIM syncs
- User imports report incomplete while Entra is still syncing
- You are orchestrating Entra provisioning with agents

## When it doesn't

- The sync itself fails (check the provisioning logs)
- The sync is quarantined (fix the underlying error)
- Users never appear even after the sync (check the mapping)

## Compatibility

Microsoft Entra ID provisioning. Agent orchestration frameworks.

## Variant phrasings

### agent timeout waiting entra sync

Same failure. The sync cycle is longer than the agent's patience.

### azure scim sync slow agent timeout

Slow is normal for large imports. Poll the logs with a long deadline.

### onboarding stuck waiting azure ad

Stuck usually means timed-out waiting. Check the real sync state first.

## Why it happens

Entra runs provisioning on a scheduled cycle, not on demand, and large imports take a while. Agents with short fixed timeouts declare failure while the sync is still legitimately running. The agent's model of the sync does not match the platform's reality.

## Edge cases

- Initial syncs are the slowest; size timeouts for the worst case, not the average
- Polling the user list can miss in-flight users; the provisioning log is the source of truth
- A sync that never finishes is a different problem; check for quarantine

## If it still fails

- Reproduce with a minimal run: one user, one file, one step.
- Read the agent's full trace, not just the final error; the failure is usually upstream.
- Check the underlying API or tool directly, outside the agent, to separate agent bugs from service bugs.
- Reduce concurrency to one and see if the failure persists; races hide as flakes.
- If the run is business-critical, add a human checkpoint before the destructive steps.

## Prevention

- Checkpoint long runs so any failure resumes instead of restarting.
- Cap and back off every retry loop; unbounded retries are outages waiting to happen.
- Validate inputs at each pipeline stage; fail fast with clear errors.
- Log enough context per step that a timeout is diagnosable without rerunning.
- Give destructive steps a human checkpoint or a dry-run mode.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_mHy4wVReSSuL4mPOefWW_g