Share this
by Lauren Ryan on May 2024
A sync error is an issue with the HubSpot Salesforce integration that prevents data from moving correctly between the platforms. It can be a property, automation, or rule keeping a record from syncing correctly. Don’t fret — a sync error doesn’t stop the entire integration or all of your records; it only affects specific records.
But don’t get too comfortable. Ignoring your sync errors can lead to wrongly triggered automations, missed sales opportunities, and unreliable marketing and sales reports, among other issues. No bueno.
How Do I Find Sync Errors in the HubSpot Salesforce Integration?
Compared to other marketing platforms, the sync error management tool is one of the most helpful features in the HubSpot Salesforce integration. Other apps don’t have this functionality, so you’re stuck guessing where something went wrong. Instead, the HubSpot Salesforce integration provides a detailed report that lists the error types, instances of each error, when it first happened, and what is causing it. Pretty neat, huh?
Go to Settings > Integrations > Connected Apps > Salesforce > Sync Health to manage your sync errors.
You can also subscribe to Sync Error Notifications. To subscribe, just go to Manage Notifications and select the frequency to receive emails immediately, daily, or weekly when new sync errors must be addressed.
A Breakdown of the Sync Error Report
Your sync error report will look something like the following image.
The first number at the top tallies the total number of errors in the account across all sync error types. Please note that this number doesn’t equal the number of affected records; one record can have multiple errors, or one error can affect numerous records, so your total number of affected records can vary.
The grid shows each sync error type and displays two numbers: First, the big, dark number tells you how many occurrences you have per error, and second, the smaller, lighter number is the number of affected records, meaning the number of records not syncing correctly because of this error.
Tackling Sync Errors in the HubSpot Salesforce Integration
You pulled your report, and it’s time to start solving errors. A good rule of thumb we follow is to start by solving the error affecting the highest number of records (again, that’s not necessarily the error with the most incidences — look at the smaller number below).
You will encounter eight types of sync errors in the HubSpot Salesforce integration.
Association Sync Errors
These errors result from a Salesforce record trying to sync with a record that’s not in HubSpot yet, or because said record hit its association limit in HubSpot. A common example is having one Account created in Salesforce that is not yet a Company in HubSpot, so there’s no Company to link it to when the Contact is syncing.
To fix an association error, you can either import all records from Salesforce or open a specific record in Salesforce and force-trigger the sync.
Custom Code Errors
There are two primary causes for this error: Salesforce Flows and Validation Rules.
Salesforce Flows are the Salesforce equivalent of HubSpot’s Workflow tool, their primary automation tool. A Flow is typically triggered when a record is updated or created, and this error essentially tells you that whatever update was made is preventing the Flow from operating.
You can address custom code errors caused by Flows by changing the data in HubSpot or updating the Flow in Salesforce to exclude HubSpot changes from triggering the Flow. Oftentimes, the change will be in HubSpot.
Next, we have Validation Rules. In Salesforce, the admin can create certain code to specify the required data for records. For example, you may have code requiring an unqualified lead to include a field with the reason. You’ll need to address this error by changing the data you’re sending from HubSpot to meet the criteria. Additionally, you can exclude HubSpot as the running user from Validation Rules to ensure HubSpot is not being held accountable for updating data that will not be updated in HubSpot. For example, if a sales team member must put in a specific update on a Contact record when an associated Opportunity reaches a certain stage, exclude HubSpot as the user from that Validation Rule. This will prevent unnecessary sync errors.
Finally, Missing Contact ID is an issue with your Apex code that prevents leads from being converted into contacts correctly. In this case, you’ll need to work with your Salesforce admin.
Duplicate Errors
This type of error can be confusing. It’s important to note that this report doesn’t give you an accurate view of your duplicate records — only the ones preventing a record from being created in HubSpot or Salesforce.
There are two types of duplicate errors. One is duplicates found in HubSpot, meaning you can’t bring this data over to Salesforce because of a duplicate. The second one, duplicates found in Salesforce, means it can’t be created in HubSpot for the same reason.
You fix this error by merging the duplicates in the respective system before syncing. If this isn’t an option, review your Matching and Duplicate Rules in Salesforce to ensure duplicates are being identified appropriately.
Permission Sync Errors
In this case, the error results from the user not having the necessary permissions to access a Field or Object in Salesforce.
A little background info: Like most integrations, HubSpot and Salesforce connect through an integration user, which is a Salesforce user whose credentials are used to sign into Salesforce from the HubSpot Settings screen. This person controls what HubSpot can access within Salesforce, and here’s where things can break.
Most people give their integration user the System Administrator Profile when setting up the integration. This means the user can access everything in Salesforce. In this case, you won’t run into permission errors. One exception to this would be insufficient access to Tasks. Even with the System Administrator profile, you must give the integration user access to the Field Task Type on the Task Object.
However, if you choose selective sync for your integration user, you’ll likely have more errors because the integration user can’t see everything on both platforms. Selective sync means that your integration user has limited access to data and actions in Salesforce.
To address errors caused by permissions, your Salesforce admin will have to tweak your integration user’s access. The only workaround you could potentially use in HubSpot is not to sync or update the affected field.
Picklist Errors
Picklist errors are the biggest cause of headaches for most. Picklists in HubSpot and Salesforce play together but don’t always run smoothly.
A picklist Field in Salesforce equates to a dropdown select Property in HubSpot. Whenever you add an option to that list in either platform, it doesn’t automatically create in the other system. So, you need to refresh fields in the integration or manually add them to the other platform.
State and country properties also often cause errors. If you use state and country picklists in Salesforce, you’ll also need to use them in HubSpot.
Additionally, Salesforce allows inactive picklist values, which means you can no longer use it when creating a record, but the integration doesn’t recognize inactive values. To circumvent this, a best practice we recommend is not to use inactive picklist values but to delete them and replace them with an active value.
Field Mapping
A field mapping error means that the data isn’t mapping correctly. This error type is uncommon. Field mapping errors typically come from the mapped fields in the integration; you will see the warnings as you go with directions on how to fix them.
Property Values Errors
This is the second most common error aside from picklist errors. This means the data type in HubSpot in this Property does not match the data type in Salesforce for this Field, or there’s an input mismatch. For example, you'll get a property value error if you have a Property with 15 characters in HubSpot, but the same Field has a 10-character limit in Salesforce.
A missing required value error means a field marked as required in Salesforce is not populated in HubSpot. Similar to picklist errors, the solutions for property value errors are case by case.
Whenever you use the integration, a big thing you want to check is what are your minimum required properties to create a Contact, Opportunity, Lead, or Account in Salesforce. Make sure you’re capturing that data in HubSpot. If you’re not giving Salesforce the minimum data it needs, you’ll see a lot of missing required value errors. This will also result in records created in HubSpot that should sync to Salesforce that are not created in Salesforce.
Other Sync Errors
Like most cases, “other” sync errors are a bucket that fits everything that doesn’t quite go in other categories.
Sync errors are typically error messages from Salesforce, and HubSpot categorizes them by type. Other sync errors are usually related to Apex, the underlying code that keeps Salesforce running. You likely won’t find many of these, but when you do, you’ll need to discuss it with your Salesforce admin because this error type is unique to your instance.
Sync Errors in the HubSpot Salesforce Integration are Not the End of the World
As you can see, a broad range of potential sync errors can prevent your data from flowing correctly between HubSpot and Salesforce. Many teams running the HubSpot Salesforce integration tend to ignore sync errors because they don’t seem to be a big deal, or on the flip side, they seem too complex to fix. But you’re not doing yourself any favors by ignoring sync errors — doing so jeopardizes the quality and integrity of your database.
A sync error doesn’t have to cause panic. A proactive approach to managing your integration’s errors will save you many headaches and keep everything flowing smoothly.
Want to feel confident managing your HubSpot Salesforce integration? Every month, we host live training sessions and go through real-life use cases to show you how to manage your HubSpot Salesforce integration in real-time. Our full training library is available exclusively to members of the Navigators community. Ready to keep learning?
