## TL;DR

The loser record has more child records (activities, notes, associations) than the merge can re-parent in one operation. Move or archive the excess children first, then merge. Merges are for the parents; the children need their own plan.

## Error

```text
Merge failed: too many child records to re-parent. Reduce child records and retry.
```

## Steps

1. Count the child records on the loser (activities, notes, attachments, associations). Expected: you know the scale of the excess.
2. Re-parent the most valuable children to the master manually or via API. Expected: the child count drops.
3. Archive or delete children with no value (old log entries, duplicate notes). Expected: further reduction.
4. Retry the merge. Expected: it succeeds within the child limit.
5. For agents, check child counts before attempting a merge and route oversized ones to the pre-processing path. Expected: no more surprise failures.

## When to use

- Merges fail on child record limits.
- An agent merges long-lived records with years of activity.
- After the failure, the records are unchanged (merge is atomic).

## When not to use

- Master selection errors (choose the master first).
- HubSpot association limits (different cap).

## Tool compatibility

- Salesforce and HubSpot merge APIs.
- Activity and note re-parenting endpoints.

## Variant phrasings

### merge failed: child limit

Re-parent or archive children first.

### too many related records to merge

Same fix from the related-records side.

## Why it happens

Merge re-parents every child in one transaction. Records that accumulated years of activity exceed the per-transaction child budget, and the whole merge rolls back.

## Edge cases

- Some child types cannot be re-parented; they must be recreated on the master.
- Archiving changes reporting history; keep an audit trail of what moved where.
- Merging in stages (children first, then parents) is slower but reliable.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_SgxAx83KUcqKFG-hTVfyEQ