# HubSpot and Salesforce sync: how it works and how to fix failures

Canonical URL: https://www.martechdevs.com/blog/hubspot-salesforce-sync

By [Jafrin Akter Alo](https://www.martechdevs.com/authors/jafrin-akter-alo)

Data Engineer and Co-founder, martechdevs

Published: 2025-01-15

Last updated: 2026-10-13

A HubSpot and Salesforce integration can be connected while the customer record your team needs is missing, stale or wrong. Troubleshoot the specific record, field and direction. Check eligibility, matching, ownership, the attempted write and the receiving system's response before starting a bulk resync. Otherwise, you can replay the same error across thousands of records.

This guide covers the native HubSpot-Salesforce integration. A custom API job, middleware connector or Smart Transfer migration has its own rules. Establish which path produced the failure before applying instructions from a different integration.

## Define what should have happened

Start with one failed business outcome: a qualified lead did not reach its owner, an account update disappeared or a closed opportunity still appears open in marketing's view.

Record the HubSpot ID, Salesforce ID, source object, destination object, field, direction, expected value and time of the change. Preserve the exact error text. A screenshot of two different values is useful evidence, but it does not tell you which value should win.

Use an incident record like this illustrative example. These are planning fields and fictional IDs, not a connector configuration or an actual incident:

```yaml
incident_id: sync-review-001
object_pair: HubSpot contact to Salesforce lead
hubspot_record_id: sample-contact-104
salesforce_record_id: sample-lead-208
field: qualification_status
source_change_at_utc: "2026-10-13T09:00:00Z"
expected_destination_value: ready_for_sales
observed_destination_value: under_review
eligibility_at_change: confirmed
mapping_rule: inspect_actual_setting
exact_error: capture_from_sync_health
business_owner: revenue_operations
repair_scope: one_representative_record
```

If you cannot identify the authoritative value, stop the resync decision and resolve ownership. Sending data faster will not settle a disagreement about what the field means.

The [lead routing guide](https://www.martechdevs.com/blog/lead-routing) separates qualification, assignment and acceptance. Use that distinction when a “sync problem” is actually a handoff with no clear owner.

## Confirm the integration and object configuration

HubSpot's connection documentation lists the supported subscription and Salesforce access requirements. It also states that installation alone does not sync all existing records, and that one HubSpot account connects to one Salesforce instance. Actions run under the connected Salesforce user's permissions. [Connection requirements and limits](https://knowledge.hubspot.com/salesforce/install-the-hubspot-salesforce-integration).

Verify the connected organisation, production versus sandbox, enabled object, creation behaviour and last successful sync. A record in a test Salesforce organisation cannot reconcile with a production record merely because the company names match.

Inspect the object version too. HubSpot's newer company sync adds controls that older company configurations do not have, including an Always use HubSpot field rule and configurable association direction. Object-level one-way direction takes precedence over field rules. [Current company-sync behaviour](https://knowledge.hubspot.com/integrations/use-the-new-company-sync-between-hubspot-and-salesforce).

Do not describe all objects as having identical options. Document contacts, companies, deals, activities and custom objects separately, including the controls actually available in your account.

## Inclusion lists are now called inclusion segments

An inclusion segment sets HubSpot-to-Salesforce eligibility. It must be active. Selecting it does not bulk-sync its existing membership. Configured Salesforce creation and first-pairing behaviour can still create or update records before membership controls ongoing updates; a changed pairing can be treated as an initial sync. Membership removal can also race with an update. [Inclusion-segment rules](https://knowledge.hubspot.com/salesforce/create-a-salesforce-inclusion-list).

Treat this as an operational filter, not a hard security boundary or a promise that data can never travel in the other direction.

For an original design example, suppose sales should receive contacts with a verified business email, an accepted qualification state and a supported region. Give each condition a defined property and owner. Then test four records: one eligible, one missing the email, one still under review and one outside the supported region.

Check membership at the time of the attempted sync. A contact that qualifies now may not have qualified when the change occurred. Retain enough event or property history to distinguish a delayed qualification from a failed write.

Avoid circular criteria. If inclusion requires a Salesforce value that can only arrive after the initial sync, the workflow may never reach the state you intended. Use a condition that the source can establish, or deliberately stage the first transfer and its later eligibility evaluation.

For Salesforce-to-HubSpot filtering, current object settings support selective-sync filters for companies on the new sync, tickets, activities and custom objects. Leads and contacts may require a different design. HubSpot's separate permissions-based selective-sync guide describes controlling the integration user's record access and requires specialist Salesforce configuration. [Object filters](https://knowledge.hubspot.com/salesforce/create-a-salesforce-inclusion-list), [permissions-based approach](https://www.hubspot.com/salesforce-selective-sync).

Do not change organisation-wide sharing to repair one missing lead without assessing who else gains or loses access. Have the Salesforce administrator verify both an allowed record and an intentionally excluded record.

## Decide which system owns each field

Write the business rule before choosing a sync rule. “Salesforce owns sales stage” is meaningful only if the team also stops other automations from rewriting that stage elsewhere.

The standard field-mapping options include Prefer Salesforce unless blank, Always use Salesforce, Two-way and Don't sync. The first allows HubSpot to fill a Salesforce blank; the second does not. Two-way uses the latest value and propagates deletions. The Owner mapping is two-way despite potentially showing a preference label. New mappings do not automatically backfill existing records, and first-sync baselines can affect the result. [Field-mapping semantics](https://knowledge.hubspot.com/salesforce/map-hubspot-properties-to-salesforce-fields).

For each business field, record:

- Its definition and responsible team.
- The system allowed to originate a change.
- The chosen mapping and any object-level override.
- What an empty value means and whether clearing it should propagate.
- The behaviour during initial pairing and later updates.
- Every workflow, import or user process that can write to it.

Consider an illustrative sales-stage field. Salesforce changes it to “Meeting scheduled”; a HubSpot workflow later writes “Qualified” based on an old score. Under an arrangement that accepts the later write, the customer appears to move backwards even though both systems successfully processed their instructions.

Repair the competing writers. Decide whether the marketing qualification state needs its own property instead of sharing the sales-stage field. A single overloaded field can make two teams fight over values that describe different parts of the journey.

For HubSpot-owned contact data, do not invent a standard Always use HubSpot option because the newer company sync has one. Check the actual object's supported configuration and whether a separate, explicitly controlled integration is needed.

## Check whether a sync was triggered

A correct mapping does not prove the connector has processed the latest change. HubSpot documents eligible creation, ownership and mapped-value events that trigger sync. A Salesforce formula recalculation alone does not trigger one; a change to a mapped input field can. [Import and trigger behaviour](https://knowledge.hubspot.com/salesforce/import-salesforce-records).

Build a timeline for the representative record: source change, eligibility, queued or attempted sync, error, retry and destination value. If the only thing that changed was a computed result, investigate the trigger before editing permissions.

Use the record's supported resync action only after you know the expected outcome. Confirm that the destination changed correctly and remained correct after other automation ran. An immediate success followed by a reversal is a different failure from an update that never arrived.

## Five failure categories to investigate

These are documented categories, not a ranking based on invented client incidents. HubSpot's Sync Health view provides error groups, affected records and exportable details. Use the exact record-level message to select the next check. [Sync Health and error reference](https://knowledge.hubspot.com/salesforce/resolve-salesforce-integration-sync-errors).

### 1. The connected user cannot perform the operation

A permission error can concern an object, field, record or attempted association. Inspect the operation that failed: reading the account, creating the lead or changing a particular field are different requests.

Check effective access for the integration identity, not the administrator looking at the screen. Salesforce recommends dedicated integration access shaped through permissions and tested against the provider's needs. That general guidance does not establish that every API-only licence fits HubSpot's native connector. [Salesforce integration-user guidance](https://admin.salesforce.com/blog/2023/best-practices-for-configuring-your-integration-user).

A useful repair record says which operation was missing, which approved permission provides it and how an excluded record remains excluded. Test the smallest representative change. Keep the access decision visible to the administrator responsible for the organisation.

If selective sync deliberately hides the record, the missing access may be correct. Reclassify the record's business eligibility before expanding access.

### 2. A picklist value is incompatible

Compare the transmitted internal value with the allowed value, not just the labels a user sees. Country and state combinations, inactive stages and owner values can create related failures. HubSpot's error reference identifies these as separate cases.

Salesforce restricted picklists prevent integrations from adding arbitrary values. That is a data-quality control worth preserving where the business needs it. [Salesforce picklist guidance](https://help.salesforce.com/s/articleView?id=000393459&language=en_US&type=1).

For a fictional example, one system uses the internal code `ready_for_sales` and another expects `sales_ready`. Agree on the intended mapping or source value. Do not add every misspelling to the destination just to empty the error queue.

Inspect the failing record's context and active options, make one controlled correction and retry it. Then fix the form, import or workflow generating the incompatible value. Repairing stored values without fixing their producer leaves a recurring incident.

### 3. A validation rule or automation rejects the write

HubSpot identifies Salesforce validation, Flow and automation failures in its error categories. The receiving system can reject a technically valid field update because the business record is incomplete.

Salesforce validation rules can make one field required conditionally on another. [Conditional required-field example](https://help.salesforce.com/s/articleView?id=000385092&language=en_US&type=1).

Imagine a qualification update that requires a verified company identifier. The source sends the qualification first, while the identifier is due in a later operation. Repeatedly retrying the first write reproduces the same missing prerequisite.

Have the admin inspect the exact rule or failed automation, then determine whether the source omitted required information, the update sequence is wrong or the rule does not represent the intended process. Test the corrected transition with both complete and incomplete records.

Keep valid controls intact. A global bypass can turn a visible sync error into quietly invalid pipeline data.

### 4. Identity or duplicate rules block the record

Salesforce applies duplicate rules during record creation, updates and upserts. Its API documentation describes these checks; it does not imply that the native HubSpot connector exposes every API override. [Salesforce duplicate-rule behaviour](https://developer.salesforce.com/docs/platform/api-rest/guide/headers-duplicaterules.html).

Compare source and destination IDs, email history, related company and the business identity of the person. Determine whether you have two representations of one person, two people sharing an address or an incorrectly paired record.

Do not remove an email or merge records merely to suppress an error. First identify which record should survive, what associations and history it must retain, and how the connector will pair it afterward. The [CRM data hygiene guide](https://www.martechdevs.com/blog/crm-data-hygiene) provides a review process for these repairs.

Keep a before-and-after record crosswalk. Once the repair changes an ID relationship, test the first subsequent sync as well as later updates. A duplicate cleanup can change which existing data is treated as the starting point.

### 5. A related record or association is missing

An activity can exist while its customer context is wrong. HubSpot documents failures where an account has not synced yet, association limits are reached or an activity has more contact associations than the integration supports.

Inspect the parent account and the IDs referenced by the child record. Repair the missing prerequisite before replaying the dependent record. A valid account name in a text field does not establish a valid account association.

The activity integration has its own association switches, selected fields and direction. Review those settings separately from activity field mappings. [Activity and association configuration](https://knowledge.hubspot.com/salesforce/sync-activities-and-tasks-between-hubspot-and-salesforce).

If the source relationship cannot be represented faithfully, document the intended projection and preserve the fuller history elsewhere. Do not erase meaningful contact relationships solely to make a connector report success. The business owner must understand what the destination will omit.

## Recover without replaying the whole database

Use a staged recovery process:

![Capture a failed record, check eligibility and pairing, inspect the trigger and error, repair a sample, replay the affected cohort and verify outcomes.](https://www.martechdevs.com/assets/blog/hubspot-salesforce-sync.svg)

Preserve the affected cohort before changing it. Select records by the actual failure condition and incident window, not by a broad “last updated this month” filter that includes unrelated work.

HubSpot shows recent API use and the allocation to its integration. Bulk resync consumes that capacity alongside other Salesforce work. Its resync documentation advises having at least three API calls per segment member available; actual consumption can vary. Treat that as a planning check, not a guaranteed per-record price or safe batch size. [API monitoring](https://knowledge.hubspot.com/salesforce/resolve-salesforce-integration-sync-errors), [resync guidance](https://knowledge.hubspot.com/salesforce/import-salesforce-records).

Agree on the batch size and stop condition with the Salesforce administrator. Watch the error type, remaining capacity and downstream customer actions. A replay can trigger workflows, so review notifications, tasks and outreach before executing it.

After each batch, verify a matched set of source and destination IDs, required fields, ownership and relationships. Keep rejected records in an actionable queue with a reason and owner. “Attempted again” is not a resolution status.

## Measure the outcome your users depend on

Use an explicitly eligible population and a business deadline. A dashboard showing the number of connected contacts does not tell you whether today's accepted leads reached sales in time.

In an original example, 700 contacts were reviewed during a fixed day. Only 500 met the agreed handoff criteria. Of those, 480 reached the correct destination owner and state within the team's deadline; twenty did not. The successful handoff rate is 480 ÷ 500 = 96%. Dividing by all 700 would incorrectly count intentionally excluded records as failures.

Suppose the twenty failures are six permission cases, five picklist cases, four validation cases, three identity cases and two association cases. Those fictional counts reconcile to twenty and help assign repair work. They are not industry frequency estimates.

Also inspect unexpected arrivals: records that should have remained excluded. Perfect delivery of the eligible cohort does not excuse transferring a separate ineligible cohort.

Track the age of the oldest unresolved failure, repeat incidents by field and failures in high-value handoffs. A small error count can still matter if every affected record is a renewal due today.

## Keep the integration maintainable

- [ ] Each object has documented direction, creation behaviour and filters.
- [ ] Required fields have definitions and a responsible writer.
- [ ] Empty values and initial sync behaviour have been tested.
- [ ] Allowed and excluded records both behave as intended.
- [ ] Picklist and validation changes include an integration review.
- [ ] Departing users and changed owners have a reassignment process.
- [ ] API capacity and sync errors have operational owners.
- [ ] Recovery batches reconcile business outcomes after automation runs.
- [ ] Schema, mapping and permission changes retain a change record.

Review this record when either team changes qualification, territory, pipeline or required fields. The integration is part of those processes, even when its settings page remains untouched.

If the current connector is becoming a permanent migration workaround, use the [Salesforce-to-HubSpot migration guide](https://www.martechdevs.com/blog/salesforce-to-hubspot-migration) to plan a controlled cutover. For continuing coexistence, [Martechdevs' CRM and lifecycle service](https://www.martechdevs.com/crm-lifecycle) can help define field ownership, repair the affected flow and establish verification the team can maintain.

## Frequently asked questions

### Why is a record missing when there is no sync error?

An error queue contains attempted operations that failed; it does not prove every expected operation was attempted. Check the connected organisation, object settings, eligibility, matching and trigger. Compare the source change time with the connector's actual activity for that record.

### Does an inclusion segment stop all Salesforce data entering HubSpot?

No. It is not a universal boundary for the reverse direction or initial pairing. Check the configured creation behaviour and the relevant Salesforce-to-HubSpot controls. Test an intentionally excluded record rather than assuming an empty segment proves isolation.

### Should every field use two-way sync?

Only if updates from both systems have an agreed meaning and competing writers are controlled. A field that describes sales acceptance may need a different owner from a marketing qualification field. Preserve those distinctions before selecting a convenient default.

### Can I fix the queue by turning off validation or duplicate rules?

That can remove the visible rejection while admitting data the business does not want. Diagnose the underlying record and rule first. Any approved change should have a defined scope, expected result and verification for records that must still be rejected.

### How do I know the repair worked?

The intended records reach the correct destination state within the agreed time, their owners and relationships remain correct, and the error does not recur after normal automation runs. Confirm that intentionally excluded records remain excluded and that the source producing the bad data was repaired too.

## Sources

1. [HubSpot: connect Salesforce](https://knowledge.hubspot.com/salesforce/install-the-hubspot-salesforce-integration). Accessed 13 October 2026.

2. [HubSpot: new company sync](https://knowledge.hubspot.com/integrations/use-the-new-company-sync-between-hubspot-and-salesforce). Accessed 13 October 2026.

3. [HubSpot: inclusion segments and selective sync](https://knowledge.hubspot.com/salesforce/create-a-salesforce-inclusion-list). Accessed 13 October 2026.

4. [HubSpot: permissions-based selective sync](https://www.hubspot.com/salesforce-selective-sync). Accessed 13 October 2026.

5. [HubSpot: property and field mappings](https://knowledge.hubspot.com/salesforce/map-hubspot-properties-to-salesforce-fields). Accessed 13 October 2026.

6. [HubSpot: imports and sync triggers](https://knowledge.hubspot.com/salesforce/import-salesforce-records). Accessed 13 October 2026.

7. [HubSpot: API usage and sync errors](https://knowledge.hubspot.com/salesforce/resolve-salesforce-integration-sync-errors). Accessed 13 October 2026.

8. [Salesforce: integration-user configuration](https://admin.salesforce.com/blog/2023/best-practices-for-configuring-your-integration-user). Accessed 13 October 2026.

9. [Salesforce: picklists and restricted values](https://help.salesforce.com/s/articleView?id=000393459&language=en_US&type=1). Accessed 13 October 2026.

10. [Salesforce: conditional validation](https://help.salesforce.com/s/articleView?id=000385092&language=en_US&type=1). Accessed 13 October 2026.

11. [Salesforce: duplicate-rule API behaviour](https://developer.salesforce.com/docs/platform/api-rest/guide/headers-duplicaterules.html). Accessed 13 October 2026.

12. [HubSpot: activity and task sync](https://knowledge.hubspot.com/salesforce/sync-activities-and-tasks-between-hubspot-and-salesforce). Accessed 13 October 2026.