HubSpot Salesforce Sync Errors: The Complete Diagnostic Playbook

The purpose of this project is to ensure a reliable, stable, and error-free sync between Salesforce and HubSpot. A consistent sync is essential for achieving full alignment across Marketing, Sales, and CS, especially because many companies tend to use HubSpot for marketing activities and Salesforce for sales operations. In these cases, the handoff between the two systems becomes critical,  and unreliable sync behavior can cause leads, MQLs, or hand-raisers to fail to reach the Sales team.

This project goes beyond simply resolving the existing sync errors displayed in the dashboards. Its goal is also to identify and address the underlying root-cause issues within the integration architecture,  not just applying temporary “band-aid” fixes,  to prevent recurring failures and ensure long-term, stable data alignment between the systems.

A fully reliable sync ensures accurate reporting, complete lifecycle visibility, reduced operational friction, and seamless collaboration between Marketing, Sales, and CS.

When to Implement

Pain Points

• Missing records or failed syncs (e.g., form submissions not appearing in Salesforce).
• Frequent duplicate or inconsistent lead data.
• Validation or field mapping errors blocking updates.
• High API usage or slow integration performance.
• MQLs or hand-raisers not reaching Sales due to unreliable system handoff 
• Unreliable lifecycle transitions between systems (misaligned qualification or ownership triggers).

Prerequisites

• Active HubSpot–Salesforce connector (Professional+ tier).
• Dedicated Salesforce Integration User with full read/write access.
• Stakeholder alignment across Marketing, Sales, and CS.
• Basic data hygiene to avoid noise during the audit (limited duplicates, no unexpected restricted access).

KPIs Affected

• Lead Response Time & MQL → SQL Conversion: Faster, more accurate lead routing when the sync is reliable.
• Attribution Accuracy: Accurate marketing → revenue flow when both systems mirror each other correctly.
• Operational Efficiency: Reduced reactive troubleshooting and manual fixes.
• HubSpot Cost Control: Preventing unnecessary marketing contact inflation (especially when Salesforce incorrectly creates marketing contacts).

Key Questions

1. ​​How does a lead enter your ecosystem?

• Through which channels (forms, ads, imports, integrations, events)?
• In which system is the record first created (HubSpot or Salesforce)?
  
  

2. When and how does a lead become a Contact or Opportunity?

• What triggers qualification?
• How is ownership assigned or transferred?
• Is this transition automated or manual?
• Does this handoff happen within one system or between HubSpot → Salesforce?

‍

3. What causes friction or data loss in the current handoff?

• Are MQLs, hand-raisers, or inbound requests failing to reach Sales?
• Are there delays, duplicates, or missing values?
• How often do Sales reps receive outdated or incomplete records?
• When the data should sync and when the data should not sync?

4. What reporting challenges exist today?

• Which metrics are inaccurate due to sync issues (conversion, velocity, attribution, ROI)?
• Which reports or dashboards are most impacted?
• Which teams depend on these views?

5. Is there a specific user to assign inactive or unowned records?
6. Who owns the ongoing maintenance of the integration long term?

‍

Tools Used

HubSpot

• Sync Health Dashboard
• Property Settings
• Duplicate Management Tool
• Error Detail & Sync Error Logs
• Error CSV Export

Salesforce

• Object Manager
• Validation Rules
• Duplicate Rules
• Integration User configuration
• Flow Builder (for diagnosing sync-blocking automation)
  
  

Additional Tools / References

• Insycle (used in many client environments for duplicate management)
• Internal documentation: error resolution notes, Loom videos, examples from past accounts
• Shared project docs (error tracker sheets, sync monitoring logs)
  
  

Scope Note

Only native HubSpot and Salesforce features are required to resolve sync errors, but external tools (such as Insycle) may support related tasks like duplicate management.

‍

Project Phases

1. Audit

• Review the HubSpot Sync Health dashboard.
• Export and categorize error logs.
• Identify patterns across error types (Permissions, Picklists, Duplicates, Associations, Validation Rules, etc.).
• Review integration user behavior and field-level sync history.

2. Plan

• Group issues by category and impact (Permissions → Mappings → Data Quality → Validation → Other).
• Outline required changes in both systems.
• Prioritize fixes based on severity, volume, and impact on the lead lifecycle.

3. Client Alignment & Question

• Validate assumptions discovered in the audit.
• Ask all questions related to:
  
  • Ownership rules
  • Lifecycle and qualification
  • Required fields or validation rules
  • Field mapping expectations
  • Duplicate management
  • Picklist governance
    
    
• Align with the client on what changes can be implemented by RevOps vs. what requires approval.

4. Execute
5. Test

• Resync corrected records and verified error clearance.
• Create new test records (in HubSpot or Salesforce) to validate field mappings, ownership, qualification criteria, and lifecycle alignment.
• Confirm that fixed errors do not reappear.

6. Document

• Record resolved issues and technical changes made.
• Update the mapping guide, field dictionary, and sync architecture documentation.
• Note any pending items requiring client decision or long-term monitoring.

7. Maintain

• Perform weekly sync monitoring (dashboard review, error trend analysis).
• Conduct quarterly audits to identify new discrepancies, deprecations, or architectural issues.
• Add new discovered errors to the playbook 

‍

Sync Errors - Salesforce <> HubSpot

‍

This session will be divided into the following topics (for each type of error)

‍

• What the error means
• Why it happens
• How to diagnose it
• How to resolve it
• Common challenges and what typically goes wrong

‍

Picklist Value Mismatch

‍

What does this Error mean?

This error occurs when HubSpot attempts to sync a value into a Salesforce picklist field, but the value is not allowed, does not exist, is inactive, or is formatted differently from the values Salesforce accepts.

Salesforce enforces strict picklist validation, so any mismatch automatically blocks the sync.

Why it happens (root causes)

A pisklist mismatch error may be caused by:

• Value exists in HubSpot, but does not exist in Salesforce
• Value exists in Salesforce, but is inactive
• Salesforce picklist is restricted, rejecting values not pre-defined
• Mismatch in label vs API name
• Differences in case, spacing, punctuation, special characters, or capitalization
• Salesforce picklist has Record Type–specific options
• Multi-select picklist receiving invalid or non-delimited values
• HubSpot contains historical values that no longer exist in Salesforce
• A Salesforce validation rule is triggered by the picklist value
• Picklist was deleted, renamed, or reorganized in Salesforce
• Automation (HubSpot workflows, Salesforce Flows, Zapier, or external APIs) writes invalid values
• Salesforce uses Country/State picklist standardization, rejecting unrecognized geographic values
• Picklist contains more options than platform allows (HubSpot and Salesforce have upper limits)
• HubSpot dropdown includes values hidden but still stored in historical data
• Field is incorrectly mapped to a Salesforce formula field (read-only)
• Integration user lacking permissions to update the field
• Picklist controlled by another picklist (dependent picklist)
• Field is part of a managed package with strict metadata validation

How to diagnose (implementation)

Step 1 — Identify the Field and Invalid Value

1. Open HubSpot → Settings → Integrations → Salesforce → Sync Errors
2. Click View Details on the impacted record
3. Note:
   
   • The Salesforce field
   • The value HubSpot tried to send
   • The Salesforce error message

Step 2 — Compare Allowed Values

In Salesforce:

1. Go to Object Manager → {Object} → Fields & Relationships → {Field}
2. Review:
   
   • Active picklist values
   • Inactive picklist values
   • Global Value Set (if applicable)
   • Whether the picklist is restricted or unrestricted

Step 3 — Compare Technical Values (API Names)

Check for mismatches in:

• Label
• API name
• Case
• Spaces
• Hidden characters
• Special characters

Salesforce validates API names, not labels.

‍

Step 4 — Check Salesforce Record Types

Identify whether the field uses Record Type–specific picklists, which may allow or block values depending on Record Type.

Step 5 — Check for Dependent Picklists

If a dependent picklist:

• Confirm the controlling field also has a valid value
• Confirm the pair (controller + dependent) is allowed

Step 6 — Check Automations

Review:

• HubSpot workflows
• Salesforce Flows
• Process Builder
• Apex Triggers
• External integrations
  
  They may insert values not allowed in the Salesforce picklist.

Step 7 — Check Validation Rules

Look for rules referencing this picklist field that may block the sync.

Step 8 — Check Country/State Standardization

If the field is:

• Country
• State/Region
  
  

Salesforce requires selecting valid standard values; mismatches block sync.

How to Fix (resolution steps)

‍

Add Missing Value to Salesforce

If HubSpot value is valid:

• Add it to Salesforce picklist
• Ensure API name matches
• Resync the record

‍

Reactivate Salesforce Picklist Value

If the value exists but is inactive:

• Reactivate it in Salesforce
• Resync the record

Align HubSpot Options to Salesforce

If Salesforce value is correct,  but HubSpot is inconsistent:

• Change the HubSpot dropdown value to match Salesforce exactly
• Update historical data
• Hide or delete invalid options

Remove Restriction in Salesforce

If Salesforce picklist is restricted:

• Set picklist to unrestricted mode, OR
• Add all HubSpot values to Salesforce manually

Fix Record Type Mapping

Ensure:

• All record types allow the value
• The correct record type is being used

Fix Dependent Picklist Rules

Update:

• Controlling field value
• Dependency matrix
  
  

Correct Multi-Select Format

Ensure multi-select values are separated by semicolon ( ; ).

Clean Invalid HubSpot Values

Use:

• Lists
• Bulk edits
• Workflows

To replace invalid values.

Adjust Salesforce Validation Rules

If validation rules prevent sync:

• Update rule OR
• Modify the record to meet the rule criteria
  
  

Remove Hidden/Legacy HubSpot Values

HubSpot may store hidden values in historical data; clean them out.

Ensure Integration User Has Permissions

Confirm:

• Edit access
• Field-level security
• Object permissions
  
  

Fix External Automations

Standardize values used by:

• Zapier
• Custom APIs
• Third-party tools
• Salesforce Flows
  
  

Common Challenges (What Typically Goes Wrong)

These are issues that do not belong in the “how to fix” section. They are pitfalls, recurring issues, and things that complicate resolution.

Salesforce admins rename labels but NOT API names

• Creates invisible mismatches.

Values deleted or inactivated without notifying the team

• HubSpot continues sending them → sync breaks.

Hidden HubSpot values still stored in historical records

• Even if option is hidden, old records still contain it.

Picklists controlled by Salesforce Record Types

• Each RT may allow different values.

HubSpot users type custom “free-text” values

• Even if the field is a dropdown, imports or workflows may insert text.

Multi-select picklists get formatted incorrectly

•  HubSpot often sends comma-delimited lists; Salesforce needs semicolon.

Country/State fields behave differently between platforms

• Salesforce rejects any value outside its standardized list.

Validation rules silently block the update

• Error appears as picklist mismatch when actually a rule is firing.

Field is restricted in Salesforce

• Salesforce rejects ANY unexpected value.

Automation loops rewrite invalid values

• After correction, flows reapply bad data.

‍

Picklist has too many options (option limit exceeded)

• Salesforce and HubSpot both impose a maximum option count.

 Picklist values rely on managed package metadata

• HubSpot cannot override or write into managed picklist structures.

Integration user cannot edit that field

• Lack of FLS or profile permissions causes false picklist errors.

Custom Code Errors

‍

What does this Error mean?

This error appears when HubSpot tries to create or update a record in Salesforce and Salesforce returns an error generated by:

• Apex Trigger
• Before/After Save Flow
• Process Builder automation
• Validation Rule
• Workflow Rule
• Assignment rule
• Formula field override
• Lookup required logic
• Managed package triggers (Pardot, CPQ, Installed Apps)

The error message will be exactly the Salesforce internal error, surfaced inside HubSpot Sync Errors.

Types of Custom Code Errors

1. Flow Error (Before-Save or After-Save Flow Failure)

Common examples:

• Missing required field set by flow
• Flow expects a value that HubSpot did not send
• Flow runs into a NULL pointer
• Flow requires user input (Screen flows accidentally triggered)
• Circular automation loop

2. Apex Trigger Exception

Examples:

• “FIELD_CUSTOM_VALIDATION_EXCEPTION”
• “REQUIRED_FIELD_MISSING”
• “Apex CPU Time Limit Exceeded”
• Try/Catch not implemented, throwing unhandled error
• Trigger requiring logic HubSpot didn’t populate

3. Process Builder Error

Examples:

• PB updates conflicting with HubSpot updates
• PB requires fields that aren’t present
• PB creates recursive updates
• PB has outdated criteria after field renaming

4. Validation Rule Blocking the Sync

Most common custom-coded error.

Examples:

• Required fields based on logic (“If Stage = X, MUST fill Reason”)
• Prohibiting certain combinations of fields
• Preventing changes when a record is in a certain state
• Date rules (close date cannot be earlier than today)

5. Managed Package Trigger Errors

Apps like:

• Pardot
• CPQ
• FinancialForce
• Conga
• Gainsight
• Custom ISVs

May enforce rules blocking HubSpot updates.

‍

6. Assignment & Routing Logic Errors

Examples:

• Assignment rule expects certain fields
• Territory model mismatch
• Auto-conversion of leads requiring fields HubSpot doesn’t populate

7. Formula Field or Read-Only Field Update Attempt

HubSpot tries to update:

• Formula field
• Rollup field
• Lookup field restricted by triggers
• Managed-package field

Salesforce returns “cannot update read-only field”.

8. Integration User Permission Block (looks like code error)

HubSpot errors often categorize permission issues under “Other,” but Salesforce may throw:

• “INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY”
• “FIELD_INTEGRITY_EXCEPTION”
  
  

These appear like code errors.

Why it happens (root causes)

• HubSpot sends data that violates a Salesforce validation rule
• Flows or triggers expect values HubSpot didn’t provide
• Automations run in the wrong order
• Salesforce enforces logic that HubSpot doesn’t know about
• Integration User lacks permissions needed by automation
• Field dependencies not met
• Triggers modify required fields but fail silently
• Process Builder conditions outdated or broken
• Sorted Picklist / Required Picklist grouping logic not met
• Unhandled Apex exception
• Circular update loops HubSpot → Salesforce → HubSpot

‍

How to diagnose (implementation)

Step 1 — Read the exact error message

HubSpot passes Salesforce’s error verbatim.

It will say things like:

• “A flow trigger failed to execute…”
• “FIELD_CUSTOM_VALIDATION_EXCEPTION”
• “CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY”
• “REQUIRED_FIELD_MISSING”
• “Apex Trigger failure on update”
  
  

Save the exact wording.

Step 2 — Identify the automation throwing the error

In Salesforce:

1. Go to Setup → Debug Logs
2. Add the Integration User to debug logs
3. Re-trigger the sync
4. Check:
   
   • Trigger stack
   • Flow errors
   • Validation rules
   • Exception type

Step 3 — Check Validation Rules

Go to:

Object → Validation Rules

Disable or update any rule that:

• Requires fields HubSpot does not populate
• Prevent edits under certain conditions
• Uses TODAY(), DATE(), or conditional formulas that block updates
• Was created recently
• Is referencing fields changed in workflow

‍

Step 4 — Check Before-Save and After-Save Flows

Check for:

• Required inputs
• Null pointer errors
• Missing default values
• Flows referencing fields HubSpot doesn’t populate
• Circular automation rewriting fields

Step 5 — Check Apex Triggers

Look for:

• Try/catch blocks missing
• SOQL queries inside loops
• Field-level assumptions (ex: “field must not be null”)
• Hard-coded record types
• Hard-coded owner logic
• Managed package triggers interfering

Step 6 — Check Assignment Rules & Routing Logic

Verify:

• Lead assignment rules aren’t expecting fields
• Auto-conversion logic isn’t failing
• Territory rules aren’t restricting

Step 7 — Verify Integration User Permissions

Check:

• Field permissions
• Object permissions
• Record Type visibility
• Apex class access
• Flow access
• CRUD/FLS mismatches

‍

How to Fix (resolution steps)

Update Validation Rules

Solutions:

• Add ISCHANGED() logic to avoid blocking updates
• Add exemptions for Integration User
• Make field conditionally required only in UI
• Use ISNEW() or PRIORVALUE() logical exceptions
• Create a bypass field for sync purposes

 Update Salesforce Flows

Examples:

• Add null checks
• Add default values
• Add conditions to avoid running flows when HubSpot updates the record
• Use “Run Asynchronously” only when needed
• Reorder flow execution if dependencies fail

Fix Apex Triggers

Possible fixes:

• Add try/catch
• Add null checks
• Remove hardcoded values
• Validate against Integration User context
• Prevent recursion
• Add bypass logic using a custom field
• Ensure test coverage handles HubSpot edge cases
  
  

Adjust Managed Package Logic

Packages like CPQ or Pardot add strict triggers.

Fixes:

• Enable package-specific bypass options
• Update package settings
• Ask vendor for recommended configuration adjustments
  
  

Update Assignment & Routing Logic

Fix:

• Lead assignment rules
• Auto-conversion triggers
• Owner routing flows
• Territory rules
  
  

Add bypass conditions for Integration User.

Grant Integration User Missing Permissions

Ensure:

• All flows/triggers can run under its context
• FLS is complete
• Record Type is correct
• Apex class access is granted
  
  

Correct Field Mapping Issues

If custom code references a field:

• Ensure it exists
• Ensure HubSpot sends valid values
• Ensure type matches SE expectations
  
  

Field Mappings Errors

‍

What does this Error mean?

HubSpot attempted to sync a field into Salesforce (or vice versa), but the mapping cannot be completed because:

• The fields are incompatible
• The mapping direction prevents the update
• The field does not exist on one side
• One of the fields is not editable
• The value does not match the field type
• The mapping was deleted or changed
• The object-to-object mapping is incorrect
  
  

Salesforce returns an error through the API, which HubSpot surfaces as a mapping mismatch or field mapping sync error.

‍

Types os Field Mapping Errors

1. Field Type Mismatch

Examples:

• HubSpot = text
• Salesforce = number
• HubSpot = dropdown
• Salesforce = multiselect
• HubSpot = date
• Salesforce = datetime
  
  

2. Unsupported Mapping Type

Fields HubSpot cannot map to Salesforce:

• Salesforce formula fields
• Salesforce roll-up summary fields
• Salesforce read-only fields
• Managed package fields
• Auto-number fields
• Lookup fields restricted by automation

3. Mapping Direction Conflict

Examples:

• Field is set to Salesforce → HubSpot
• But HubSpot tries to overwrite it
• Field is set to HubSpot → Salesforce
• But Salesforce triggers modify the field

4. Field Deleted or Renamed in Salesforce

Mapping remains active, but the field:

• Was deleted
• Was renamed
• Was moved to another object
  
  

HubSpot keeps trying to sync to a field that no longer exists.

‍

5. Field Hidden by FLS (Field-Level Security)

Integration user cannot edit the field, causing a mapping failure.

6. Object-Level Mapping Incorrect

Examples:

• Mapping Contact → Account level field
• Mapping Lead field to Contact field incorrectly
• Mapping Company → Account misaligned

7. Multi-Select Mapping Errors

Salesforce expects semicolon-separated values,

HubSpot sends comma-separated, causing mismatch.

8. Picklist Mapping Without Matching Allowed Values

Field is mapped correctly, but the value:

• Does not exist
• Is not valid
• Is inactive
  → Salesforce rejects it.

(Note: This is related to Picklist Errors but triggered through field mapping.)

9. Validation Rules Blocking Mapped Fields

Validation rules requiring fields that HubSpot does not populate.

10. Required Field Missing in Mapping

Salesforce field is required, but HubSpot does not send it.

11. Read-Only Fields in Salesforce

HubSpot attempts to update:

• Formula
• Auto-number
• Roll-up
  
  → Sync error returned.
  
  

12. Duplicate Mapping of the Same Field

Occurs when:

• Two HubSpot fields map to one Salesforce field
• A Salesforce field is mapped in multiple objects
• A mapping conflict exists in child/parent fields

13. HubSpot Custom Property Missing Mapping

A field was created in HubSpot but never mapped to Salesforce even though Salesforce requires it.

14. Record Type–Specific Mapping Issues

Salesforce field availability depends on Record Type; HubSpot cannot set values for Record Types where field is hidden.

‍

Why it happens (root causes)

• Data types don’t match
• Mapping direction not aligned with business rules
• Salesforce field is required or read-only
• Mapping references a deleted field
• Integration User lacks FLS
• Validation rules enforce constraints
• HubSpot sends null/blank values that Salesforce blocks
• Salesforce uses dependent fields not mapped
• Picklist values don’t match
• HubSpot uses hidden legacy values
• Duplicate mappings conflict
• External automations reset or overwrite fields

‍

Diagnosis (implementation)

STEP 1 — Read the HubSpot Sync Error Message

Common messages:

• “Field is read-only in Salesforce”
• “Invalid field type for mapping”
• “Value cannot be set on this field”
• “Required field missing”
• “Cannot update field due to permissions”
• “Field does not exist”

STEP 2 — Identify the Mapped Properties

In HubSpot:

Settings → Integrations → Salesforce → Field Mappings

Locate:

• HubSpot property
• Salesforce field
• Mapping direction
• Field type (HS + SF)

STEP 3 — Validate Field Type Matching

Compare:

• HubSpot property type
• Salesforce field type
• Acceptable values (for picklists)
• Multi-select vs single-select

STEP 4 — Check Salesforce Field-Level Security

Go to:

Setup → Profiles → Integration User → Field-Level Security

Validate:

• Visible
• Editable
• Read-only status
  
  

STEP 5 — Confirm the Salesforce Field Exists

Go to:

Object Manager → {Object} → Fields

Check if field:

• Exists
• Was renamed
• Is active
• Is on the correct object

STEP 6 — Check Validation Rules

Confirm if rule requires:

• Value HubSpot does not send
• Conditional requirements HubSpot breaks
• Logic blocking API calls
  
  

STEP 7 — Check Record Type Availability

Field may be:

• Visible on some RTs
• Hidden on others
  HubSpot cannot send values to hidden fields.

STEP 8 — Check for Duplicate Mappings

Look for:

• Two HubSpot fields mapping to same SF field
• Mapping conflicting across objects

‍

How to Fix

Align Field Types

Examples:

• Convert HubSpot text → dropdown
• Convert Salesforce number → text
• Convert HubSpot multiple checkbox → Salesforce multiselect picklist
• Standardize date/datetime
  
  

Correct Mapping Direction

Options:

• Make mapping bidirectional
• Or set:
  
  
  
  • Salesforce → HubSpot
  • HubSpot → Salesforce

Based on business rules and system of record.

Remap or Recreate Deleted Fields

If Salesforce field was deleted:

• Create replacement
• Update mapping
• Resync records

Fix Field-Level Security

Enable:

• Read
• Edit
• Visibility for the Integration User.
  
  

Update Validation Rules

Modify rule so that:

• Integration User bypasses it
• Fields are conditionally required
• HubSpot null values are allowed
  
  

Handle Picklist Dependencies

If picklist is dependent:

• Ensure controlling field is also mapped
• Ensure values align
  
  

Fix Multi-Select Issues

HubSpot must send:

• Semicolon-separated values (;)
  
  

Remove Duplicate Mappings

Ensure each Salesforce field:

• Maps to exactly ONE HubSpot property
  
  

Add Missing Required Fields

If Salesforce field is required:

• Map
• Populate via workflow
• Or evaluate making it conditionally required
  
  

Do Not Map Read-Only Fields

Remove mapping to:

• Formula
• Roll-up
• Auto-number
• Managed fields
  
  

‍

Common Challenges

1. Field types change over time

Admin updates Salesforce type without updating HubSpot mapping.

2. Salesforce admins rename fields

HubSpot mapping breaks silently.

3. Duplicate mappings created accidentally

Two HubSpot fields writing into one Salesforce field.

4. HubSpot users import invalid values

Even if the mapping is correct.

5. HubSpot fields still contain legacy hidden values

Old invalid values cause sync failures even after mapping correction.

6. Salesforce dependent picklists require controller values

HubSpot often forgets to populate the controller field.

7. Record Type differences cause field mismatches

RT-based fields not available to Integration Users.

8. Validation rules trigger as “mapping errors”

Even though mapping is technically correct.

9. Mapping direction misaligned with business logic

Sales becomes system of record, but mapping is HS → SF.

10. Impossible mappings

Formula fields

Auto-number fields

Roll-ups

Managed fields

HubSpot cannot update them.

‍

Property Values

‍

What does this Error mean?

The sync failed because the value inside the field does not meet Salesforce’s requirements.

The field mapping is usually correct,  the problem is the data itself.

Examples:

• Value is not valid for the Salesforce field
• HubSpot sends null, but Salesforce requires a value
• HubSpot sends text where Salesforce expects numeric
• Format does not match Salesforce validation rules
• Value violates a Salesforce validation rule
• Field length exceeded
• Picklist value not allowed
• State/Country values invalid
• Multi-select values incorrectly formatted
• Lookup or Owner references invalid

Types of Property Value Errors

‍

1. Invalid Format (most common)

Examples:

• Text → Number
• String → Boolean
• Wrong decimal/thousands format
• Invalid email or phone
• Wrong URL format
• Wrong date vs datetime (HubSpot date is UTC-based)

2. Null or Missing Required Values

Salesforce requires a field that HubSpot didn’t populate.

Examples:

• Required Lead fields
• Required Opportunity fields
• Required Reason fields
• Required Date fields
• Required Picklists
• ‍

3. Value Exceeds Maximum Length

Examples:

• Description too long
• Long URL
• Long free-text value

4. Unsupported Special Characters / Encoding Issues

Includes:

• Emojis
• Multi-byte characters
• Smart quotes
• HTML tags
• Hidden whitespace

5. Invalid Picklist Value

Value exists in HubSpot but not in Salesforce picklist.

(Overlaps with Picklist Errors but originates from “invalid property value”)

6. Multi-Select Format Errors

HubSpot sends:

• comma-separated values

Salesforce expects:

• semicolon-separated values

7. Boolean/Checkbox Mismatch

Examples:

• HubSpot sends “true”, Salesforce expects “1”
• HubSpot sends null to a Salesforce checkbox that doesn’t allow null
  
  

8. Invalid Lookup / Reference Value

Examples:

• OwnerId not valid
• AccountId missing
• Lookup refers to a deleted record
• Owner is inactive

9. Hidden Legacy HubSpot Values

Historical data containing:

• Old picklist values
• Old formats
• Deprecated values hidden in UI

‍

10. Dirty Data from Imports

HubSpot imports often include:

• Wrong capitalization
• Invalid phone formats
• Spaces
• Extra commas
• Bad email addresses

11. Validation Rules Blocking the Value

Salesforce validation rules enforce:

• Conditional requirements
• Dependencies
• Formatting logic

HubSpot cannot bypass these unless explicitly configured.

12. State/Country Standardization Conflicts

Salesforce uses ISO-standard picklists.

HubSpot often uses free text.

Examples:

• “United States” vs “USA”
• “California” vs “CA”
• Salesforce requires Country if State is provided

‍

13. Managed Packages Requiring Specific Values

CPQ, Pardot, Conga, Gainsight, FinancialForce, etc.

ROOT CAUSES (WHY THIS HAPPENS)

• HubSpot accepts non-standard values; Salesforce does not
• Salesforce requires values HubSpot does not send
• HubSpot sends invalid or legacy values
• Salesforce performs strict format validation
• Dependent picklists require controlling field values
• Null values are not allowed
• External tools write invalid data
• Validation rules enforce UI-only logic on API calls
• Lookup references do not exist or are inactive
• Salesforce uses standardized Country/State lists
• Value length exceeds Salesforce limits

DIAGNOSIS (IMPLEMENTATION — STEP BY STEP)

STEP 1 — Read the HubSpot Sync Error Message

Typically says:

• “Invalid value”
• “Value not allowed”
• “Value does not meet field requirements”
• “Required field missing”
• “Value exceeds maximum length”
• “Invalid reference Id”
  
  

Record the SFDC field + the value attempted by HubSpot.

STEP 2 — Check Salesforce Field Configuration

Go to:

Object Manager → {Object} → Fields & Relationships → {Field}

Check:

• Field type
• Length
• Required?
• Validation rules
• Picklist allowed values
• Dependent picklists
• Reference/Lookup constraints

STEP 3 — Inspect the Value in HubSpot

Check if:

• Value has hidden whitespace
• Value contains deprecated options
• Value was inserted manually
• A workflow overwrote it
• The import created bad formatting

STEP 4 — Check Automations

Review:

• Salesforce Flows
• Apex triggers
• Process Builder
• HubSpot workflows
• Zapier/Make automation

They may be overwriting values incorrectly.

STEP 5 — Check Field Dependencies

Salesforce may require:

• Stage Reason when Stage = Closed Lost
• State when Country exists
• Contract Start when Type = Customer
  
  

STEP 6 — Check Integration User Permissions

FLS issues often manifest as:

“Invalid value” or “cannot update field”.

IMPLEMENTATION — HOW TO FIX

Clean or Standardize Data in HubSpot

Normalize:

• Type
• Formatting
• Capitalization
• Whitespace
• Special characters

Replace Invalid Values with Allowed Values

Especially for:

• Picklists
• Checkboxes
• Multi-select fields

Update Field Types to Match

Examples:

• HubSpot dropdown → Salesforce picklist
• HubSpot text → Salesforce number
• Salesforce multiselect picklist → HubSpot multiple checkboxes

Add Default Values in HubSpot

If Salesforce requires:

• Lifecycle Stage
• Lead Source
• Type
• Rating
• Stage Reason
  
  

Add default values or workflow automation.

Update Salesforce Validation Rules

Options:

• Add “Integration_User__c = TRUE” bypass
• Make field required only for UI (ISCHANGED logic)
• Modify logic to allow null on API updates

‍

Fix Multi-Select Formatting

Ensure values are separated with:

• semicolon (Salesforce requirement)
  
  

Fix Lookup & Reference Fields

Options:

• Reassign Owner
• Fix Account/Contact lookups
• Create missing lookup targets
• Replace invalid references

Remove Hidden Legacy Values

Use:

• Lists
• Bulk edits
• Workflows
• Ops tools
  
  to clean outdated or invisible values.
  
  

Ensure Country/State Standardization Matches Salesforce

Use:

• ISO codes
• Valid SFDC picklist values
• HubSpot Country/State dropdowns

‍

6. COMMON CHALLENGES (SPECIFIC TO PROPERTY VALUE ERRORS)

1. HubSpot accepts “any” value — Salesforce does not

Huge gap between allowed vs. strict values.

2. Hidden characters break validation

Whitespace or invisible characters in text fields.

3. Legacy HS values causing silent failures

Data from past imports or workflows.

4. Multi-select differences (comma vs semicolon)

Very common in HubSpot–Salesforce sync.

5. Validation rules intended for UI block API updates

Users forget to add API exceptions.

6. Dependent picklists not aligned

HubSpot ignores dependencies.

7. Owners or lookup values invalid

Inactive owners or deleted related records.

8. External tools introduce invalid formats

Zapier, Make, APIs — write wrong values often.

9. State/Country standardization mismatch

Salesforce uses strict lists; HubSpot doesn’t.

10. Salesforce limits (255 char text fields)

HubSpot descriptions often exceed the limit.

‍

Associations

WHAT THIS ERROR MEANS

The sync failed because:

• HubSpot tried to associate records in a way Salesforce does not support
• Salesforce could not find the associated record
• Salesforce requires a parent record before child records
• Salesforce requires only one primary relationship where HubSpot allows multiples
• Lookup fields in Salesforce require a valid record ID
• Required parent relationships are missing
• HubSpot is associating objects that Salesforce does not connect by default
• Deprecated records or invalid lookups block the sync
• Sync direction restrictions prevent associations from being written
• Salesforce validation rules block association updates

TYPES OF ASSOCIATION ERRORS

1. Parent Record Missing

HubSpot tries to sync a Deal → Company, but Salesforce cannot find the related Company.

Common messages:

• “Parent record not found”
  
  
• “Company does not exist in Salesforce”
  
  
• “Account ID is required for this Opportunity”
  
  

2. Multiple Companies Associated to a Contact

HubSpot allows multi-company associations.

Salesforce only supports one Account per Contact.

Error examples:

• “Contact cannot have more than one Account”
• “Multiple company associations not supported”
  
  

3. Invalid Lookup ID

Salesforce lookup tries to reference a record that:

• Does not exist
• Is deleted
• Is inactive
• Is outside user visibility
  
  

4. Child Record Syncing Before Parent Record

HubSpot syncs Deal/Contact before syncing Company → Salesforce blocks the association.

5. Restricted Association Type

Examples:

• HubSpot associate deal → contact with pipelines not matching SFDC restrictions
  
  
• Custom association labels not supported in Salesforce
  
  

6. Unsupported Association Structure

Salesforce does not support:

• Associating multiple Contacts to multiple Companies
  
  
• Multiple parent Accounts
  
  
• Custom object → unsupported object associations (unless lookup exists)
  
  

7. Duplicated Associations

HubSpot tries to recreate an association already existing in Salesforce, causing:

• Duplicate key errors
  
  
• Conflict resolution failures
  
  

8. Required Relationships Missing

Examples:

• Opportunity requires an Account
  
  
• Case requires Contact
  
  
• Quote requires Opportunity
  
  

HubSpot may not enforce these.

9. Deleted Parent Record

Parent Account deleted → child Contact/Deal can’t sync.

10. Sync Direction Restrictions

Association sync set to:

• HubSpot → Salesforce only
  
  
• Salesforce → HubSpot only
  
  HubSpot tries to push a relationship that’s blocked.
  
  

11. Invalid Custom Object Relationships

Salesforce requires:

• Lookup fields
  
  
• Master-detail rules
  
  HubSpot may try to create a relationship not represented by any SFDC lookup.
  
  

12. Pipeline-Specific Restrictions

Some Salesforce orgs require:

• Account on Opportunities
  
  
• Contact Role on Opportunities
  
  
• Opportunity Contact Role as required
  
  

HubSpot does not enforce OCRs.

ROOT CAUSES (WHY THIS HAPPENS)

• HubSpot allows flexible associations → Salesforce does not
• Salesforce requires strict lookup relationships
• HubSpot syncs records out of order
• Missing Account/Company mapping
• Required parents missing
• Required child objects missing
• Parent record deleted or inactive
• External tools inserted inconsistent associations
• Custom validation requiring relationship rules
• Salesforce dependent validation between associated objects
  
  

DIAGNOSIS (IMPLEMENTATION — STEP BY STEP)

STEP 1 — Read the HubSpot Sync Error Message

Look for indications like:

• “Parent record does not exist”
• “Invalid reference Id”
• “Association type unsupported”
• “Required relationship missing”
  
  

STEP 2 — Identify the Parent–Child Relationship

Example questions:

• Is this a Contact needing a Company?
• Is this an Opportunity needing an Account?
• Is this a Case needing a Contact?
  
  

STEP 3 — Check if the Associated Record Exists in Salesforce

Verify:

• Record exists
• Record wasn’t deleted
• Integration User has visibility
• IDs match
  
  

STEP 4 — Check Required Relationship in Salesforce Configuration

Example:

• Opportunity → requires Account?
• Case → requires Contact?
• Custom Object → master-detail set correctly?
  
  

STEP 5 — Check HubSpot Associations

HubSpot may have:

• Multiple companies associated to a Contact
• Deals associated to Companies not synced
• Custom association labels unsupported by SFDC
  
  

STEP 6 — Check Sync Order

HubSpot may sync:

• Deal before Company
• Contact before Account
• Activity before Contact
  
  

STEP 7 — Check Salesforce Validation Rules

Example validation rules that block association:

• “Opportunity must have Primary Contact Role”
• “Account must be active before association”
• “Record cannot be associated with inactive Account”

STEP 8 — Check If Sync Settings Restrict Associations

Examples:

• Only Salesforce → HubSpot allowed
  
• Company sync disabled

‍

IMPLEMENTATION — HOW TO FIX

Create or Sync the Parent Record First

Example:

• Sync Company (Account) before syncing Contact
• Sync Account before syncing Opportunity
  
  

Remove Extra Company Associations

For Contacts:

• Set a single Primary Company in HubSpot
• Unassociate secondary companies (or map correctly)
  
  

Fix Incorrect or Deleted Lookup IDs

Replace:

• Broken Account IDs
• Deleted Contact lookups
• Invalid Owner references
  
  

Map Associations Properly in Field Mappings

Ensure:

• Deal ↔ Company associations mapped
• Contact ↔ Company mapping correct
  
  

Add Missing Required Relationships

Examples:

• Add Account to Opportunity
• Add Contact Role to Opportunity
• Add Company to Contact
  
  

Update Salesforce Validation Rules

Allow:

• Integration User bypass
• API exceptions
• Conditional requirements only for UI
  
  

Clean Up Inactive or Deleted Parent Records

Reassign:

• Deals to new Accounts
• Contacts to active Companies
  
  

Adjust Automation Logic

Fix or disable:

• HubSpot workflows overwriting associations
• Salesforce flows reassigning objects incorrectly
• External integrations injecting invalid associations
  
  

Align Custom Object Relationships

Ensure HubSpot custom object mapping matches:

• Salesforce lookup fields
  Master-detail hierarchy
  
  

COMMON CHALLENGES (SPECIFIC TO ASSOCIATIONS)

1. HubSpot allows flexible object relationships

Salesforce does not — biggest challenge.

2. Contacts with multiple Companies break SFDC sync

Since Salesforce supports only one Account per Contact.

3. Opportunities require Accounts

HubSpot often syncs Deals without a Company.

4. Salesforce lookup fields reject invalid IDs

Even whitespace or old IDs break sync.

5. Sync order issues

Mid-pipeline sync errors when child objects sync before parents.

6. Data imported historically

Creates ghosts associations that Salesforce cannot interpret.

7. Validation rules triggered by associations

Salesforce often requires:

• Primary Contact Role
• Active Account
• Required lookup
  
  

8. External tools create invalid associations

Zapier, Make, and APIs assigning wrong Account IDs.

9. HubSpot association labels do not exist in Salesforce

SFDC only supports lookup fields.

10. Parent record deleted in Salesforce

HubSpot tries to sync associations to invalid records.

‍

Permissions

Permission Errors occur when HubSpot attempts to create or update a record in Salesforce, but the Integration User lacks the required access (permissions, visibility, field access, role hierarchy, sharing rules, or API rights).

WHAT THIS ERROR MEANS

Salesforce blocked the sync because the Integration User cannot perform the attempted action, such as:

• Create record
• Edit record
• Update mapped fields
• View record
• View parent/related record
• Update object due to owner/record visibility
• Update field due to FLS restrictions
• Assign owner
• Write into restricted picklists
• Access restricted validation rules
• Create associated objects (OCRs, Activities, etc.)
  
  

HubSpot is ready to sync — Salesforce denied the request.

‍

TYPES OF PERMISSION ERRORS

1. Field-Level Security Denied (MOST COMMON)

The Integration User cannot read or write a field.

Examples:

• “INVALID_FIELD_FOR_INSERT_UPDATE”
• “INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY”
• “You cannot update this field”
  
  

2. Object Permission Missing

Profile does not allow:

• Create
• Read
• Edit
• Delete
  
  

Common for:

• Opportunity
• Account
• Lead
• Task
• Custom objects
  
  

3. Record-Level Access / Visibility Issues

Salesforce sharing rules block edit or visibility.

Causes:

• Private org-wide defaults
• Restricted role hierarchy
• Sharing rules missing
• Owner outside visibility
  
  

4. Missing Access to Parent Record

Integration User cannot view/edit parent:

• Account
• Contact
• Opportunity
• Custom object related via lookup
  
  

5. Owner Assignment Permission Errors

HubSpot tries to assign:

• An inactive owner
• A user the Integration User cannot “see”
  
  
• A queue the user has no access to
  
  

6. API Access Disabled or Restricted

Profile without:

• API Enabled
• Modify All Data
• View All Data
  
  

7. Permission Set Not Assigned to Integration User

Missing:

• Access to custom objects
• Access to managed packages (CPQ, Conga, Gainsight)
• Access to HubSpot SFDC package fields
  
  

8. Validation Rules Requiring UI-Only Fields

If a validation rule requires a field value that the Integration User cannot access → permission error.

9. Owner-Based Sharing Violations

Exemple:

• Integration User attempts to update record owned by someone they cannot view.
  
  

10. Record Type Access Missing

Integration User cannot create/update records with certain record types.

11. Missing CRUD Access via Profile

Example:

• Integration User cannot create Opportunities
• Integration User cannot edit Contacts
  
  

12. Managed Package Dependencies

CPQ, Pardot, Gainsight, FinancialForce add:

• Extra required fields
• Restricted objects
• Locked record types
  
  

13. Permission Conflicts from Flows or Apex

Flows running “User Context” will fail if they require a field the Integration User cannot see.

ROOT CAUSES (WHY THIS HAPPENS)

• Integration User does NOT have a fully-permissioned profile
• Salesforce is configured with private sharing model
• Field-Level Security blocks read/write
• Validation rules require fields the Integration User cannot update
• Owner assignment is restricted
• Record type access missing
• Managed packages impose stricter access rules
• Salesforce Admin modified permissions without syncing with HubSpot settings
• Integration User created incorrectly (not API/Integration specific)
• External tools created restricted records
• Role hierarchy prevents visibility
  
  

DIAGNOSIS (IMPLEMENTATION — STEP BY STEP)

STEP 1 — Read the HubSpot Error Details

Common phrases:

• “Salesforce rejected the update”
• “Field not accessible”
• “Insufficient access rights”
• “INVALID_FIELD_FOR_INSERT_UPDATE”
• “INSUFFICIENT_ACCESS_OR_READONLY”
• “Cannot update record owner”
  
  

STEP 2 — Identify Which Field/Object Failed

HubSpot error will indicate:

• Record type
• Field name
  
  
• Operation attempted
  
  

STEP 3 — Log In as the Integration User in Salesforce

Use:

Setup → Login as User

→ attempt the same action manually.

If the user cannot:

• Update the field
• View the field
• Edit the record
  
  

You’ve found the root cause.

STEP 4 — Check Permissions

Check ALL of these:

Object Permissions

• Create
• Read
• Edit
• Delete
  
  

Field-Level Security

• Visible
• Editable
  
  

Sharing Rules

• Read/write access
  
  

Record Type Access

• Available record types
  
  

Profile settings

• API Enabled
• Modify All
• View All
• Edit Tasks
  
  

STEP 5 — Check Owner & Visibility Rules

Is the Integration User able to:

• See the record owner?
• Assign that owner?
• Edit a record from another team?

STEP 6 — Check Validation Rules

Many errors come from rules like:

AND(

  ISBLANK(Stage_Reason__c),

  ISPICKVAL(StageName, "Closed Lost")

)

If Integration User cannot write Stage_Reason__c → sync error.

STEP 7 — Check Apex/Flows

Flows in “User Context” fail due to missing permissions.

IMPLEMENTATION — HOW TO FIX

Assign a Full-Permission Profile

The Integration User should have:

• API Enabled
• Full CRUD for standard objects
  
  
• Full CRUD for custom objects
• Modify All Data (optional but recommended)
• View All Data
  
  

Add Proper Permission Sets

Include access to:

• Custom fields
• Custom objects
• HubSpot package fields
• Managed package fields
  
  

Fix Field-Level Security

Ensure all mapped fields are:

• Visible
• Editable
  
  

Add Sharing Rules

Give integration user:

• Read/Write access to Accounts, Contacts, Deals
• Visibility based on business rules
  
  

Fix Validation Rules

Add bypass conditions:

$User.Alias = "integration" 

or

$Profile.Name = "Integration User"

‍

Fix Owner Assignment

• Reactivate missing owners
• Grant visibility for all owners
• Allow assignment to queues
  
  

Enable Required Object Permissions

Examples:

• “Edit Tasks”
• “Create Events”
• “Edit Opportunities”
  
  

Grant Record Type Access

Allow Integration User to access all record types used in HubSpot.

Update Managed Package Access

For packages:

• CPQ
• FinancialForce
• Gainsight
• Pardot
  
  

Give access to required objects.

Reconfigure Flows/Apex to Run as System Context

Avoid requiring user-level permissions.

‍

COMMON CHALLENGES (SPECIFIC TO PERMISSION ERRORS)

1. Integration User is created incorrectly

Often created with too few permissions.

2. Admins forget to update FLS when adding new fields

Result: sync breaks only for new fields.

3. Validation rules block API updates

Rules written for UI users cause sync failures.

4. Private sharing model blocks edits

Integration User cannot edit what it cannot “see”.

5. Salesforce Role Hierarchy restricts visibility

Not aligned with HubSpot workflows.

6. Multiple record types with different access

HubSpot may create a record with a record type the Integration User cannot access.

7. Managed packages restrict actions

CPQ and similar tools introduce hidden permission dependencies.

8. Custom Apex triggers require fields the Integration User cannot see

Very common in mid-market orgs.

‍

Other

The Other Errors category includes all sync issues that do not clearly fit into standard buckets such as Permissions, Picklists, Field Mappings, Ownership, Associations, or Property Values.

These errors usually appear when HubSpot receives an unexpected or generic error response from Salesforce and the root cause is not immediately obvious. They tend to be:

• Unpredictable
• Less intuitive
• Highly situational
• Often dependent on complex Salesforce configurations
• Triggered by multiple overlapping factors

In practice, “Other” errors often originate from things like:

• Temporary Salesforce API failures or timeouts
• API rate limits being reached
• Record locking conflicts
• Background automation (Flows, Process Builder, Apex triggers) that rejects changes
• Misaligned pipelines or record types
• Managed packages (CPQ, Pardot, Gainsight, FinancialForce) enforcing hidden rules
• Recently deleted, merged, or deprecated fields and objects
• Partial data inconsistencies or corrupted values
• System-level behaviors that HubSpot does not surface clearly
  
  

Because these errors are typically uncommon, opaque, and dependent on deep Salesforce logic, they require more investigation than the standard sync error types.

This is also the category that will continually grow over time as new edge cases appear across different clients and org configurations.