Help for owners
My HubSpot and Salesforce sync is failing, paused or missing records
Short answer
The sync usually fails for one of a few reasons HubSpot documents: the Salesforce integration user lacks permissions, API limits are reached, a mapping or picklist does not match, or a Salesforce rule blocks the record. Open the Sync Health tab in HubSpot to see the error type before changing any setting.
Does this sound like your situation?
- New leads or contacts are in one system and not the other.
- HubSpot says the Salesforce integration is suspended or shows sync errors.
- Some fields update and others stay stale.
- Data overwrote itself, or two systems keep changing the same field.
- It worked until someone changed Salesforce fields, users or permissions.
Why does this happen?
The integration user is missing permissions
HubSpot lists the permissions the Salesforce integration user needs: API Enabled, the HubSpot Integration permission set, and read and edit access to the synced objects and the fields on them, including related objects. Without them records fail or syncing is suspended.
Confirmed by knowledge.hubspot.com
API limits are reached
Syncing is suspended when the Salesforce API limit is exceeded or when the number of calls allocated to HubSpot is too low. HubSpot's Sync Health tab shows API use over the last 24 hours.
Confirmed by knowledge.hubspot.com
Salesforce itself can block the record
HubSpot names custom code, such as Salesforce automations, flows or validation rules, as a cause, and duplicate rules on the Salesforce side. A Salesforce admin has to review those.
Confirmed by knowledge.hubspot.com
Mappings and picklists no longer match
HubSpot lists incompatible property and field types, missing or invalid Salesforce IDs, picklist values that do not match, inactive owners or stages and invalid values such as a malformed email.
Confirmed by knowledge.hubspot.com
Sync rules decide which system wins
Each mapping has a sync rule, such as prefer Salesforce unless blank, always use Salesforce, two-way or do not sync. Mapping one property to several fields can overwrite values or create loops, and a new mapping does not backfill existing values on its own.
Confirmed by knowledge.hubspot.com
What can I do about it today?
- Open the sync errors screenIn HubSpot, go to Connected Apps, open Salesforce and look at the Data sync tab and its Sync Health view. Note the error types and counts. You can export the list.
- Read the suspension message if there is oneHubSpot shows the reason for a suspension, such as an API limit, missing permissions or an outage.
- Check Salesforce for outagesHubSpot's checklist includes the Salesforce Status page.
- Ask what changed in SalesforceFind out whether anyone changed fields, picklists, users, profiles or automations around the time it started failing.
- Do not press Clear Suspension or resync in bulk before the cause is fixedHubSpot says to fix the cause first, then clear the suspension or resync. Bulk resync works up to 100 errors at a time.
- Do not edit mappings or sync rules in a hurryA wrong rule can overwrite good data in either system. Export or screenshot the current mappings first.
When should I bring someone in?
- The same errors return after you fix them.
- Records are being overwritten and you cannot tell which system is right.
- The sync depends on Salesforce custom code nobody on your side understands.
How do I handle it?
- Group the errorsI export the sync errors and group them by type, so one cause is not mistaken for many.
- Read the vendor documentationI work from HubSpot's and Salesforce's own documentation for each error type and for the permissions required.
- Check the Salesforce side with its adminValidation rules, flows, duplicate rules and the integration user's access are reviewed with whoever administers Salesforce.
- Test with a few recordsI try the fix on a small number of records in a sandbox or on test records before a bulk resync.
- Record the mapping and rulesI write down each mapping and its sync rule, so a future change is planned and not accidental.
The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.
What do owners ask about this?
How many errors can I resync at once?
HubSpot says up to 100 errors at once. To sync more, import the records from Salesforce or update a mapped property.
Why did syncing stop completely?
HubSpot lists reasons such as an exceeded API limit, disabled API access, missing permissions, a locked record, full Salesforce storage, an outage or missing mappings.
Will a new mapping fill in old records?
Not by itself. HubSpot says existing values need a resync or an import.
Can I delete a standard mapping?
HubSpot says only custom mappings can be deleted. To stop a standard mapping, set its rule to do not sync.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.