HubSpot and Salesforce sync errors: what causes them and how to fix them

Start with the sync health screen

In HubSpot, open the Salesforce integration settings and go to sync health. Errors are grouped by type, with the affected records listed under each one. Export them, sort by error type, and fix the biggest group first. Fixing the cause of one group often clears hundreds of records at once.

1. Picklist mismatches

This is usually the largest group. A HubSpot dropdown value does not exist in the matching Salesforce picklist, or the Salesforce picklist is restricted. Country and state fields are the classic example, along with lead source, industry and lifecycle related fields.

• Make the options match exactly on both sides, including spelling and capital letters.
• If Salesforce uses state and country picklists, use the same standard values in HubSpot forms.
• When you add a new value in one system, add it in the other on the same day. Put that rule in your change process.

2. Validation rules and required fields

Salesforce validation rules exist for good reasons, but they were usually written with a sales rep in mind, not an integration. If a rule needs a phone number or an industry before a lead can be saved, every HubSpot contact without that value will fail.

Either make sure HubSpot always sends the value, or add a bypass for the integration user in the rule. A common pattern is a custom permission assigned to the integration user that the validation rule checks for.

3. Duplicate rules

HubSpot deduplicates on email. Salesforce deduplicates on whatever your duplicate rules say. When those disagree, the sync gets blocked. You might also have one HubSpot contact matching both a lead and a contact in Salesforce.

• Decide on one matching logic and make both systems follow it.
• Set duplicate rules to allow with an alert for the integration user, or adjust them so the sync is not blocked.
• Merge existing duplicates in Salesforce first, then let HubSpot catch up.

4. Permissions on the integration user

The HubSpot integration connects as one Salesforce user. If that user cannot see a field, edit an object, or own records of a certain type, you get permission errors. This often appears after someone adds a new field and forgets field level security for the integration user. Give the integration user its own profile or permission set, and update it every time you add a mapped field.

5. Field mapping problems

Mappings break when field types do not match, when a field is deleted on one side, or when a text value is too long for the target field. Review the mappings at least once a quarter. Remove anything nobody uses, and for each mapped field decide which system wins when both have a value. HubSpot lets you choose a sync rule per field, such as Prefer Salesforce unless blank, Always use Salesforce, or Two way. Pick each one on purpose rather than leaving the default.

6. Custom code and automation in Salesforce

Flows and Apex triggers can fail when a record arrives from the integration in a state they did not expect. The error message in HubSpot will often point to a flow or a trigger by name. Fix the automation so it handles missing values, or exclude the integration user where the automation is not needed.

7. API limits

Every Salesforce org has a daily API call limit, shared between every connected tool. Big imports, enrichment tools and bulk updates in HubSpot can eat through it and delay the sync. Check the API usage setting in the integration, and schedule large data jobs outside business hours.

Keep it clean after the fix

• Use an inclusion list so only the contacts sales needs go to Salesforce.
• Review sync health weekly for a month after a cleanup, then monthly.
• Keep a simple mapping document: field, direction, which system wins, and who owns it.
• Make any new field or picklist value a change on both sides, never just one.