# Fix agent failing to reconcile duplicate users from HR CSV import

## TL;DR
The agent cannot reconcile duplicates because the CSV and the system match on different keys. Define one canonical matching rule, usually email, dedupe the CSV on it first, then match against existing users. Reconciliation is a data problem before it is an agent problem.

## The error
```text
Agent failed
Could not reconcile duplicate users from HR CSV import. 30 rows matched multiple existing users.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=agent failed to reconcile duplicate users from hr csv import"
```

## Fix it

### Step 1: Pick the canonical match key

```bash
Choose one field, usually work email, as the identity key for matching.
```

Expected: Every row and every existing user has a value for the key.

### Step 2: Dedupe the CSV on that key

```bash
Find rows sharing the key and resolve them: keep the newest, merge, or flag for review.
```

Expected: The CSV has one row per key.

### Step 3: Match against existing users

```bash
For each row, look up the existing user by the key.
```

Expected: Each row matches zero or one user, never many.

### Step 4: Quarantine the ambiguous rows

```bash
Rows that still match multiple users go to a human review list, not into the import.
```

Expected: The import proceeds on clean rows; ambiguous ones wait for a human.

### Step 5: Verify the import

```bash
Compare imported users against the CSV.
```

Expected: No duplicates created; quarantined rows are tracked.

## When this applies

- Agents cannot reconcile duplicate users from HR imports
- HR CSVs create duplicate accounts
- You are building HR-to-system provisioning

## When it doesn't

- The CSV is malformed (fix the file first)
- The target API rejects the users (check the API errors)
- Duplicates come from another source (fix that source)

## Compatibility

HR CSV imports generally. Any identity matching logic.

## Variant phrasings

### duplicate users hr csv import agent

Same failure. One match key plus CSV dedup resolves it.

### agent cannot match csv rows to users

Unmatchable rows need a defined key. Without one, matching is guessing.

### hr import duplicate accounts

Duplicates are created when the importer cannot tell same from different. The key is the answer.

## Why it happens

HR exports are messy: name changes, rehires, and inconsistent emails mean rows do not line up with system users on any single field the agent assumes. Without an explicit canonical key and a dedupe pass, the agent matches ambiguously and either duplicates or fails.

## Edge cases

- Rehires are the hardest case; decide whether they get a new account or the old one reactivated
- Email changes break email-keyed matching; keep a stable employee id as backup
- Log every match decision so duplicates are auditable later

## 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_p8O64PI4xgQpK6zAJIj5aw