HubSpot Salesforce Sync Errors: Diagnostic Playbook

A HubSpot-Salesforce sync can look healthy while important records are failing in the background. The connector stays connected, most records continue moving, and the problem only becomes visible when Sales asks why a hand-raiser never reached Salesforce or RevOps notices that the two systems disagree.

That's what makes these issues easy to underestimate. A sync error usually affects a specific record, field, or transaction. It doesn't necessarily shut down the integration. One validation rule can block a group of inbound leads while everything around them continues to sync normally.

The right way to troubleshoot this is to look for patterns. Fixing individual records can clear today's queue, but if the underlying field mapping, Salesforce rule, permission, or automation stays the same, the errors will come back.

This playbook covers how we approach that diagnosis, what each HubSpot Salesforce sync error category usually points to, and where to look before changing anything.

Why Does a Reliable HubSpot-Salesforce Sync Matter?

For most teams using both platforms, the integration sits directly in the handoff between Marketing and Sales. HubSpot may capture and qualify the prospect, while Salesforce becomes the place where Sales manages the relationship. When that handoff breaks, the business impact can show up before anyone notices a technical problem.

A form submission might stay in HubSpot instead of reaching Salesforce. A sales rep might see an old owner or lifecycle stage. Marketing and Sales might report different funnel numbers because a field stopped updating between the systems.

Those problems affect more than CRM cleanliness. They can delay follow-up, distort reporting, and make people distrust the systems they're supposed to use.

That's why we treat sync health as part of the revenue process. The goal is to know that the records and fields people rely on are moving correctly.

When Should You Audit Your HubSpot-Salesforce Sync?

You don't need to wait for the integration to stop working. In practice, the better trigger is usually a pattern that doesn't make sense.

Maybe form submissions aren't appearing in Salesforce when expected. Maybe reps are finding duplicate records or seeing information that doesn't match HubSpot. Lifecycle stages may change unexpectedly, or reports built from each system may start telling different stories.

Those are good reasons to open the Sync Health dashboard and investigate.

The same applies after a meaningful system change. A new Salesforce validation rule, a new HubSpot workflow, a field change, or a permissions update can affect the integration even when nobody touched the connector itself. If a new cluster of errors appears, check what changed recently before you start repairing records one by one.

What Should You Understand Before Fixing Sync Errors?

Start with the process the integration is supposed to support. You need to know where records enter, which system owns the important fields, and what is supposed to happen when the record moves from Marketing to Sales.

For example, if both HubSpot and Salesforce can update Lifecycle Stage, you need to know which value should win when they disagree. HubSpot field mappings can be configured with different sync rules, including two-way sync and rules that favor Salesforce. Those choices determine what happens when either system changes a mapped value.

You should also understand which records are supposed to sync at all. HubSpot inclusion segments can restrict which HubSpot records are eligible to sync to Salesforce, while selective sync is available for supported Salesforce objects moving in the other direction. A record that isn't eligible under those rules may be behaving exactly as configured. Our guide to inclusion lists vs. selective sync covers how the two work together.

Before changing anything, answer the basic ownership questions. Where is the record created? What qualifies it for Salesforce? Which platform owns each important field? Who owns the integration when something changes?

Without those answers, it's easy to fix an error in a way that creates a different problem somewhere else.

What Tools Should You Use to Diagnose the Sync?

Start in HubSpot. The Salesforce integration's Sync Health area shows current sync errors, affected records, API usage, and the details HubSpot received from Salesforce. You can also export the error list and resync records after the source issue has been corrected.

On the Salesforce side, the tools depend on the error. Object Manager helps with field types and picklists. Validation Rules and Flow Builder matter when Salesforce is rejecting an update. User permissions tell you whether the connected user can actually read or edit the object and field HubSpot is trying to touch.

For harder automation issues, Salesforce debug information can help you trace what fired during the update. The important part is to diagnose both sides. HubSpot may be where you see the error, while Salesforce is where the rule causing it lives.

How Should You Work Through a Sync Error Backlog?

First, get the full picture. Open Sync Health, export the current errors if the backlog is large, and look at the number of records affected by each issue. HubSpot currently shows the current error count and the impacted records for each error type.

Prioritize based on business impact. An error blocking high-intent inbound leads deserves attention before a low-volume formatting problem on a field nobody uses in routing or reporting.

Then look for shared causes. If 40 records are failing because the same Salesforce validation rule rejects an empty field, you have one system problem affecting 40 records. Fix that rule or the data feeding it before resyncing the records.

After the change, test the scenario that failed. Resync the affected records, then create or update a test record that follows the same path. A cleared error queue doesn't tell you whether the next record will fail for the same reason.

Document the change when you're done. At minimum, the next admin should be able to see which fields sync, which direction they sync, and which Salesforce rules or automations interact with those fields.

How Do You Find Sync Errors in HubSpot?

Go to Settings, then Integrations, Connected Apps, Salesforce, and Data Sync. Under Sync Health, HubSpot shows cards for the current error categories and the records they affect. You can open an error to see more detail, view the affected records, export the list, and resync errors after you've corrected the cause. HubSpot's own guide to resolving Salesforce sync errors walks through each screen.

This is also where you should turn on notifications. HubSpot supports instant, daily, or weekly sync error notifications. Daily works well for most teams because someone sees new problems quickly without getting an email for every individual failure.

Don't rely on somebody remembering to open this page. Give one person ownership of the review.

How Do You Read the Sync Health Report?

Start with the records affected. A large number of error events doesn't always mean a large number of broken records, and one underlying issue may repeat across the same population.

HubSpot currently groups Salesforce sync errors into eight categories. The label helps narrow the investigation, but the Salesforce message inside the error usually tells you much more about the actual cause.

Treat the category as the starting point. A validation rule, for example, may surface through a custom code error even though nobody would describe the rule itself as "custom code."

Before working through the categories one by one, check five causes that show up behind almost every type: a Salesforce validation rule firing, the connected user missing a field or object permission, a managed package such as CPQ or Pardot enforcing its own rules, multi-select values separated by commas instead of semicolons, and an automation rewriting a value right after you correct it. A surprising number of errors trace back to one of these.

How Do You Fix Picklist Sync Errors?

Picklist errors happen when one system sends a value the other system can't accept. Salesforce is especially strict when a picklist is restricted, because the incoming value has to match an allowed option.

Check the exact value HubSpot attempted to send, then compare it with the current Salesforce values. Internal values matter. A label that looks identical to a person can still fail if the underlying values don't match.

Country and state fields deserve extra attention because Salesforce can enforce State and Country/Territory picklists. HubSpot documents specific errors when the internal values don't match Salesforce's available values. Inactive Salesforce owners and opportunity stages can also appear in the picklist category.

Once you find the mismatch, decide which system reflects the real business definition. Update the values there, align the other system, clean the affected records, and resync.

Avoid adding a new picklist value simply to make an error disappear. If the value shouldn't exist in your process, fix the source that created it. For restricted picklists, global value sets, and multi-select formatting in more depth, see our guide to fixing Salesforce picklist sync errors.

How Do You Fix Custom Code Errors?

HubSpot uses the Custom code category for Salesforce automation and rules that reject an incoming update. HubSpot's current examples include Salesforce automation, custom field validation rules, missing Contact IDs, and Salesforce Flow errors.

Read the exact Salesforce message before touching the record. A message containing FIELD_CUSTOM_VALIDATION_EXCEPTION points to a validation rule, REQUIRED_FIELD_MISSING means a field Salesforce requires came through empty, and CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY usually means a Flow or Apex trigger failed during the update. If the message doesn't point you somewhere specific, reproduce the update with the connected user and trace what Salesforce executes.

Validation rules are a frequent source of trouble because a rule that works perfectly for a Salesforce user can still reject an API update from HubSpot. Maybe Salesforce requires Lead Source whenever Status changes, while HubSpot is allowed to create the record without Lead Source.

Flows can create similar problems when they assume a field will always be populated or when they react differently to records created by the integration.

Change the rule only after you understand why it exists. Sometimes HubSpot needs to send better data. Sometimes the Salesforce automation needs a condition that handles integration updates correctly.

How Do You Fix Property Mapping Errors?

Property mapping errors point to a problem with the relationship between a HubSpot property and a Salesforce field.

The field types may be incompatible. The Salesforce field may have been removed. A reference field may be receiving something that isn't a valid Salesforce ID. HubSpot requires compatible field types when creating mappings, and the sync rule controls how values move once the mapping exists.

Open the mapping and check both fields. Confirm that they still exist, that the types are compatible, and that the selected direction matches your data ownership model.

Be careful with newly created mappings. HubSpot notes that existing values don't automatically sync retroactively just because a mapping was added. You may need to resync records or use an import afterward.

Also avoid creating custom mappings for Salesforce Lead ID or Contact ID fields that the connector already manages. HubSpot warns that mapping default Salesforce ID fields manually can cause unexpected sync behavior.

How Do You Fix Property Value Errors?

With a property value error, the mapping may be fine. The data inside the field is what Salesforce or HubSpot rejects.

Common examples in HubSpot's current documentation include a string that's too long, an invalid email, a missing required value, an invalid owner assignment, or a value that violates a uniqueness rule.

Look at the failed record first. Compare the value with the receiving field's requirements. Check field length, formatting rules, required fields, and any Salesforce validation rules that reference that field.

Imports often expose these problems in bulk. A spreadsheet can introduce old options or values that looked harmless before they reached a stricter Salesforce field.

Correct the source data, then resync the affected records. If the same error appears across many records, fix the process creating the bad value before working through the backlog. Our property and association errors guide goes through each property value error type individually.

How Do You Fix Association Errors?

Association errors happen when the relationship HubSpot is trying to sync doesn't fit the relationship available in Salesforce, or when one of the related records hasn't synced yet.

HubSpot's current examples include waiting for an Account to sync, reaching an association limit, and association cardinality mismatches. For activities, the integration supports syncing one Contact association to Salesforce, so an activity connected to multiple HubSpot Contacts can create a mismatch.

Start by identifying the two records that are supposed to be related. Confirm that both exist on the Salesforce side and that the connected user can access them.

Sync order can matter as well. If the related parent record isn't in place yet, the child record may have nowhere valid to connect.

Be especially careful when your HubSpot association model is more flexible than the corresponding Salesforce relationship. Decide how that relationship should translate before you repair the individual records.

How Do You Fix Permission Errors?

Permission errors mean the Salesforce connected user can't complete the action HubSpot requested. The user's Salesforce permissions determine what HubSpot can read and change through the integration. In the error details, these usually show up as INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY (no access to a related record) or INVALID_FIELD_FOR_INSERT_UPDATE (the field isn't editable for that user).

When one field starts failing while other records still sync, check field-level access. This often happens after a Salesforce admin adds a new field but doesn't give the integration user permission to read or edit it.

For broader failures, check object permissions and access to the affected records. HubSpot specifically calls out insufficient access and missing field permissions as common errors in this category.

A dedicated integration user makes this much easier to manage because you know exactly which permissions the connector is using. Whatever user you connect, treat its permissions as part of the integration architecture and review them when new objects or fields are added. Our permission errors guide covers how to set that user up.

How Do You Handle Duplicate Sync Errors?

Duplicates deserve their own investigation because HubSpot and Salesforce don't always identify matching records the same way.

HubSpot's Sync Health dashboard includes duplicate errors such as an email address already being used on a HubSpot Contact or a Salesforce duplicate rule blocking the sync (DUPLICATES_DETECTED in the Salesforce message). HubSpot recommends reviewing the relevant Salesforce matching rules when the duplicate rule originates there.

Before merging anything, work out which records are already paired between the systems. Remapping a HubSpot record to a different Salesforce record can behave like a new initial sync, which means mapped values may write back during that new pairing.

Fix the existing duplicates, then inspect how they were created. The long-term fix may live in Salesforce duplicate rules, HubSpot record-creation behavior, or the way records are allowed into the sync. The CRM deduplication playbook covers the cleanup itself.

Company records need similar attention. HubSpot currently advises against turning on automatic company creation and association by contact email domain when the Salesforce integration is active because the setting can create duplicate company records.

What Are "Other" or Unknown Sync Errors?

The Other / Unknown category catches errors that don't fit cleanly into the standard groups.

One documented example occurs when someone manually maps a default Salesforce ID field, such as Lead ID or Contact ID, to the corresponding HubSpot Salesforce ID property. The integration manages those IDs itself, so HubSpot advises against adding those custom mappings.

Other errors in this bucket can be more configuration-specific. Read the Salesforce response carefully and check what changed around the time the error started.

If the error message doesn't point to a field, rule, or mapping you can trace, HubSpot recommends contacting Support for unknown errors.

Which Sync Failures Never Look Like Errors?

Some of the most damaging sync failures are easy to miss because the connector still looks healthy and records keep moving. You usually find them when someone notices a missing lead or a field that keeps changing without explanation.

Validation rules are a common example. A prospect can fill out a form ready to buy, HubSpot captures the submission, and Salesforce rejects the record because a validation rule added months ago requires a field such as Lead Source. The failure appears in HubSpot's Sync Health dashboard, but that only helps if someone checks it or has error notifications turned on. Otherwise, Sales may never know the prospect existed. In RevBlack integration audits, it's common to find dozens of errors that have been sitting there unreviewed.

Automation collisions are harder because they may produce no connector error at all. A HubSpot workflow might reset a lifecycle stage that Salesforce just updated, or a Salesforce Flow might react to a HubSpot change and write another value back. The symptom is usually data that seems to change on its own, such as lifecycle stages reverting or jumping without a clear trigger. Before changing either automation, map everything that can fire on the affected fields in both systems and trace the order of events.

Turn on Sync Health notifications (daily works for most teams) and give one person ownership of a weekly review.

How Do You Prevent Import-Related Sync Errors?

Treat imports as changes to the integration.

Before importing, check that the data matches the fields it will eventually reach. Look for invalid emails, old picklist options, missing required values, and values that exceed Salesforce field limits.

Also understand what the import will trigger. HubSpot notes that Salesforce imports can trigger further syncing depending on inclusion-segment settings, and large imports may take longer while HubSpot manages Salesforce API usage.

Test a small sample first if the import will touch important lifecycle, ownership, or routing fields. It's much easier to stop ten bad records than clean up ten thousand.

Why Does the HubSpot-Salesforce Sync Sometimes Look Delayed?

A delay doesn't automatically mean the connector is broken. HubSpot checks for new or updated information across the two platforms approximately every 15 minutes and triggers syncs when needed based on the integration configuration. Many events can also trigger syncs directly, including form submissions and mapped property updates. Our list of HubSpot-Salesforce sync triggers covers which events fire a sync right away.

When someone reports a delay, check whether the record is eligible to sync and whether anything happened that should have triggered the sync. Inclusion-segment criteria and field mapping rules can affect what moves.

If the expected trigger happened and the record still isn't moving, check Sync Health before assuming the delay is normal.

How Do You Manage Salesforce API Limits?

HubSpot uses Salesforce API calls to move information between the systems, and those calls count against the Salesforce organization's API allocation. HubSpot lets you see usage over the previous 24 hours and control how many Salesforce calls are allocated to the integration.

A single Contact sync can use multiple API calls, depending on what needs to sync. Salesforce's API allocation is also shared with other tools connected to the organization.

If usage is consistently high, look at the volume you're sending through the integration. Inclusion segments can limit which HubSpot records are eligible to sync to Salesforce, and selective sync is available for supported objects coming from Salesforce.

Bulk work deserves extra care. Imports and large updates can consume calls quickly, so plan them around the rest of your integration activity rather than treating API capacity as unlimited.

How Should You Set Up the Integration to Reduce Future Errors?

A lot of sync trouble starts with decisions made during setup.

Pay close attention to the Salesforce connected user. HubSpot performs Salesforce actions according to that user's permissions. If the user can't access an object or edit a field, the connector can't do it either.

Review every field mapping instead of accepting two-way sync by default. Decide which platform should own the value and choose the corresponding sync rule. If both systems are allowed to write to a field, make sure there's a reason for it.

Limit record volume intentionally. If only qualified Contacts need to enter Salesforce, an inclusion segment can keep other HubSpot Contacts out of the sync until they meet your criteria.

If Salesforce Accounts sync with HubSpot Companies, review HubSpot's automatic company creation setting as well. HubSpot currently advises against using automatic company creation and association alongside the Salesforce integration because of the risk of duplicate Companies.

Finally, test the setup with the records your business actually uses. A basic test Contact won't expose a validation rule that only fires on an MQL or a Flow that only runs when ownership changes. The HubSpot Salesforce integration guide covers the full setup.

How Do You Keep the Integration Healthy After the Errors Are Fixed?

Give the integration an owner.

That person should review Sync Health weekly, follow up on new patterns, and know which teams need to be involved when a Salesforce or HubSpot change affects the sync.

Daily error notifications are a useful backup, but they don't replace the weekly review. The dashboard is where you see whether the same error is spreading across more records or whether a supposedly fixed issue has returned.

Changes should also have a lightweight governance step. When someone adds a Salesforce validation rule, changes a picklist, or creates automation on an important mapped field, the integration owner should know about it.

You don't need a meeting for every CRM edit. You do need enough visibility to connect a new error with the change that caused it.

Keep your field mapping and automation documentation current. When a future admin has to troubleshoot why Lifecycle Stage keeps reverting, they should be able to see which system writes to it and what automation runs afterward.

Where Should You Start If the Sync Is Already Messy?

Start with Sync Health and the lead handoff.

Find out whether high-intent inbound records are currently failing to reach Salesforce. Those deserve attention first because the business impact is immediate.

Then work through the recurring error patterns by records affected. Fix the source problem, resync the backlog, and test the same scenario with a new record.

Once the visible errors are under control, investigate the stranger symptoms: lifecycle stages that change on their own, ownership that keeps reverting, reports that disagree for reasons nobody can explain. Those often point to automation or data ownership conflicts that won't always show up as a traditional sync error.

A clean integration still needs someone watching it. HubSpot and Salesforce will keep changing, and the connection between them has to change with them.

If you'd like a second set of eyes on your Sync Health report, book a sync audit with us. We'll find the patterns behind the errors and tell you what to fix first.