HubSpot Salesforce Field Mapping Errors: Diagnosed & Fixed

Your HubSpot-Salesforce sync is broken. You know this because a sales rep just told you a lead never showed up in Salesforce,  a lead that filled out a form three days ago and has since gone cold. Or because your Sync Health Dashboard is showing errors you've never seen before and the error message reads like it was written for a Salesforce developer, not a RevOps team.

The good news: most sync failures trace back to one of two root causes. Fix those, and you resolve the majority of what's breaking.

This guide covers both in full,  what the error means, why it happens, how to diagnose it, and how to resolve it. No assumptions about what's already been configured. Start at whichever section describes what you're seeing.

Part 1: Picklist Value Mismatch

What this error means

A picklist mismatch error occurs when HubSpot tries to sync a value into a Salesforce picklist field, but Salesforce rejects it. The value either doesn't exist in Salesforce, is inactive, is formatted differently from what Salesforce expects, or violates a restriction on that field.

Salesforce enforces strict picklist validation. Any mismatch,  even a difference in capitalization or a trailing space, automatically blocks the sync. The record doesn't move. No alert fires. The error accumulates in your sync log while your data quietly falls out of alignment.

Why it happens

Picklist mismatches have more root causes than almost any other sync error type. The most common:

Value exists in HubSpot but not in Salesforce. Someone added a new option in HubSpot without adding the corresponding value to the Salesforce picklist. Or the Salesforce value was deleted or inactivated without updating HubSpot.

Label vs. API name mismatch. Salesforce validates against API names, not display labels. A Salesforce admin can rename a label without changing the API name,  or vice versa, creating an invisible mismatch that's nearly impossible to spot without checking both.

Case, spacing, or special character differences. "New Business" and "new business" are different values to Salesforce. A trailing space, an em dash instead of a hyphen, or a hidden character from a data import can all cause rejections.

Restricted picklist rejecting undefined values. When a Salesforce picklist is set to restricted mode, it rejects any value not explicitly defined, including values that work fine in unrestricted fields.

Record Type–specific picklist options. If your Salesforce org uses Record Types, different Record Types may allow different picklist values. A value that's valid for one Record Type is invalid for another. The sync error gives you no indication which Record Type is the problem.

Dependent picklist logic. If a picklist is controlled by another picklist (e.g., Sub-Industry depends on Industry), both fields need valid, paired values. If the controlling field has an invalid value, the dependent field sync fails too.

Multi-select picklist formatting. HubSpot often sends multi-select values as comma-delimited lists. Salesforce requires semicolons. This single formatting difference blocks every multi-select sync until it's corrected.

Country/State standardization. If your Salesforce org uses State and Country picklist standardization, it only accepts values from a defined list of ISO standard names. Any non-standard entry — "USA" instead of "United States", "CA" for California without a valid country pairing — gets rejected.

Automation writing invalid values. HubSpot workflows, Salesforce Flows, Zapier automations, or external APIs may be inserting values that don't exist in the Salesforce picklist. The sync isn't the source of the bad value,  the automation is. Fixing the sync error without fixing the automation means the error comes back.

Integration user permission gap. If the integration user lacks field-level security access to edit a specific picklist field, the sync fails in a way that looks like a picklist mismatch but is actually a permissions issue.

Managed package restrictions. Picklists that are part of managed packages (CPQ, Pardot, FinancialForce, etc.) often have strict metadata validation. HubSpot cannot override or write into these structures without package-specific configuration.

How to diagnose it

Step 1: Identify the field and the rejected value. Go to HubSpot → Settings → Integrations → Salesforce → Sync Errors. Click View Details on the affected record. Note three things: the Salesforce field that errored, the exact value HubSpot tried to send, and the full Salesforce error message. Copy it verbatim — you'll need it.

Step 2: Compare allowed values in Salesforce. In Salesforce, go to Object Manager → select the object → Fields & Relationships → find the field. Check: the list of active picklist values, any inactive values, whether the picklist uses a Global Value Set, and whether the picklist is set to restricted or unrestricted mode.

Step 3: Compare API names, not just labels. Don't just look at what the values are called, check their API names. In Salesforce, the API name is what gets validated during sync, not the display label. A label that looks identical can have a different API name if it was renamed after creation.

Step 4: Check for Record Type–specific picklists. If your org uses Record Types, check whether the affected field has different value sets per Record Type. Identify which Record Type the failing record is assigned to and verify that the value HubSpot is sending is allowed for that specific Record Type.

Step 5: Check for dependent picklist logic. If the failing field is a dependent picklist, check the controlling field on the same record. If the controlling field has an invalid or missing value, the dependent field sync fails regardless of whether the dependent value itself is valid.

Step 6: Check automations writing to this field. Review HubSpot workflows, Salesforce Flows, Process Builder automations, Apex Triggers, and any external integrations (Zapier, custom APIs) that write to this field. Any automation that inserts a value not in the Salesforce picklist will regenerate the error after you fix it, unless you fix the automation too.

Step 7: Check Country/State standardization. If the failing field is a Country or State/Region field and your org has State and Country picklist standardization enabled, cross-reference the value HubSpot is sending against Salesforce's list of accepted ISO standard values.

How to fix it

Add the missing value to Salesforce. If the value HubSpot is sending is legitimate and should exist in Salesforce, add it. Make sure the API name matches exactly,  not just the label. Then resync the affected records.

Reactivate the inactive value. If the value exists in Salesforce but is set to inactive, reactivate it. Then resync.

Align HubSpot options to Salesforce. If Salesforce's values are the correct reference and HubSpot is inconsistent, update the HubSpot dropdown to match Salesforce exactly. Update any historical records that contain the old values and hide or delete the invalid options from HubSpot.

Remove the restriction or add all values. If Salesforce is set to restricted mode and is rejecting valid values, either add the HubSpot values to the Salesforce picklist manually, or switch the picklist to unrestricted mode if your data governance allows it.

Fix Record Type mapping. Verify that all relevant Record Types allow the value being sent. If a specific Record Type is blocking it, update the picklist assignment for that Record Type.

Fix dependent picklist rules. Update the controlling field value and the dependency matrix so the combination of controlling + dependent values is valid in Salesforce.

Fix multi-select formatting. Ensure multi-select values syncing from HubSpot are semicolon-delimited, not comma-delimited. This often requires updating the HubSpot workflow or integration configuration that prepares the value before sync.

Clean historical HubSpot values. Use HubSpot lists, bulk property edits, or workflows to identify and replace any records still carrying invalid picklist values,  including values that are hidden in HubSpot's UI but still stored in historical data.

Fix the integration user's field-level security. If the integration user lacks edit access to the picklist field, grant the correct permissions at the profile or permission set level. Then resync.

Fix external automations. For any Zapier integration, custom API, or third-party tool writing invalid values to this field, update the automation to use values that exist in the Salesforce picklist. A sync fix without an automation fix produces the same error on the next run.

Common pitfalls

Admins rename labels but not API names. This creates invisible mismatches that look identical on screen but fail validation. Always check API names explicitly.

Values deleted or inactivated without team notification. HubSpot keeps sending deleted values. The error compounds silently until someone checks the sync log.

Automation loops rewrite invalid values after correction. You fix the record, the sync clears, then a workflow fires and reapplies the bad value. Always audit automations before marking a picklist error resolved.

Validation rules surface as picklist errors. Sometimes a Salesforce validation rule fires when a picklist field is updated, and the error appears in HubSpot as a picklist mismatch. The actual cause is the validation rule, not the value. Check validation rules if the standard picklist fixes don't resolve the error.

Part 2: Custom Code Errors

What this error means

A custom code error appears when HubSpot tries to create or update a record in Salesforce, and Salesforce returns an error generated by its own internal automation or logic — not by the sync configuration itself.

The error message HubSpot displays is exactly what Salesforce returned: the raw internal error, surfaced verbatim in your Sync Errors dashboard. It will look like developer output — "FIELD_CUSTOM_VALIDATION_EXCEPTION", "CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY", "Apex CPU Time Limit Exceeded" — because it is. Salesforce generated it internally and passed it back.

The most common sources of custom code errors:

Apex Triggers. Custom code that runs automatically when a record is created or updated. If the trigger expects a field value that HubSpot didn't send, throws an unhandled exception, or hits a CPU time limit, the sync fails.

Before-Save and After-Save Flows. Salesforce Flows that fire on record changes. If a Flow has a null pointer error, requires a field HubSpot didn't populate, or runs into a circular update loop, it blocks the sync.

Validation Rules. The most common custom code error source. A validation rule that requires a field to be filled under certain conditions, prohibits certain field combinations, or enforces date logic will reject any HubSpot update that doesn't satisfy the rule, even if the sync configuration is correct.

Process Builder automations. Legacy automation that may conflict with HubSpot updates, require fields that aren't present, or create recursive update loops.

Managed package triggers. Apps like Pardot, CPQ, FinancialForce, Conga, and Gainsight add their own trigger logic that runs on every record update. These triggers can block HubSpot writes without any obvious connection to the integration.

Assignment and routing logic. Lead assignment rules, territory models, or auto-conversion logic that expects specific field values may fail when HubSpot creates or updates records without those values.

Read-only field update attempts. If HubSpot's field mapping includes a formula field, rollup field, or managed-package field, Salesforce returns "cannot update read-only field." This appears as a custom code error.

Why it happens

The underlying pattern is the same across almost every custom code error: HubSpot sends data that violates a rule or expectation Salesforce has, and Salesforce enforces that rule without warning.

The integration wasn't configured with knowledge of that rule. The rule may have existed before the integration was set up. It may have been added afterward by a Salesforce admin who didn't know the integration was running. It may be part of a managed package that was installed independently. In every case, the result is the same,  the sync fails, and the error message tells you what rule is fired but not where to find it.

How to diagnose it

Step 1: Read the exact error message. Copy the full error text from HubSpot's Sync Errors dashboard. It will tell you the error type and often the name of the rule or trigger that fired. Common messages: "A flow trigger failed to execute", "FIELD_CUSTOM_VALIDATION_EXCEPTION", "REQUIRED_FIELD_MISSING", "Apex Trigger failure on update", "CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY". Save the exact wording before doing anything else.

Step 2: Enable debug logs on the integration user. In Salesforce, go to Setup → Debug Logs. Add the integration user to the log list. Set the log level to capture Apex, Flow, and Validation detail. Re-trigger the sync on a failing record. Then review the debug log output,  it will show you the full trigger stack, which Flow or Apex ran, what the exact failure point was, and what field values were present at the time of failure.

Step 3: Check Validation Rules. Go to the relevant object in Salesforce → Validation Rules. Look for rules that: require fields HubSpot may not populate, prevent edits when a record is in a certain state, use TODAY() or DATE() formulas that produce unexpected results, or were added recently. Test each relevant rule against the field values HubSpot is sending.

Step 4: Check Before-Save and After-Save Flows. Review all active Flows on the object. Look for null pointer conditions, required input values HubSpot doesn't send, missing default values, and circular update logic. A Flow that was built for manual data entry often fails when the same update comes from an integration because the integration doesn't populate every field the Flow expects.

Step 5: Check Apex Triggers. Look for triggers that have missing try/catch blocks, null field assumptions, hardcoded owner or Record Type logic, SOQL queries inside loops (which can hit governor limits), or managed package triggers running alongside custom code.

Step 6: Check assignment and routing logic. Verify that lead assignment rules aren't expecting field values HubSpot doesn't populate. Check that auto-conversion logic and territory rules have appropriate fallback conditions for records created by the integration user.

Step 7: Verify integration user permissions. Confirm the integration user has: edit access on all relevant fields (field-level security), access to all relevant Record Types, permission to execute the Apex classes and Flows that run during sync, and CRUD access on all syncing objects. Permission gaps often surface as custom code errors rather than permission errors because Salesforce returns the automation's error rather than the access error.

How to fix it

Update Validation Rules to exempt the integration user or handle null values. The most effective pattern: add $User.Username != 'integration@yourorg.com' as a bypass condition, or use ISCHANGED(), ISNEW(), and PRIORVALUE() logic to make the rule conditional rather than absolute. Make fields conditionally required only in the UI, not in the underlying database rule, so the integration can write without violating the constraint.

Update Flows to handle null inputs and integration context. Add null checks and default values to every Flow that runs on objects the integration touches. Add conditions that skip Flow execution when the record is being updated by the integration user. Use "Run Asynchronously" where appropriate to prevent timing conflicts. If a Flow is creating a circular update loop with HubSpot, add a bypass field,  a checkbox that HubSpot sets on write to signal that the Flow should not re-fire.

Fix Apex Triggers. Add try/catch blocks. Add null checks on every field assumption. Remove hardcoded values for owner, Record Type, and required fields. Add bypass logic using a custom bypass field or checking the integration user's profile context. Ensure test coverage handles scenarios where HubSpot sends records with incomplete data.

Adjust managed package logic. Packages like CPQ and Pardot add strict trigger logic that's often configurable at the package level. Enable package-specific bypass options where available. Update package settings to allow integration user writes. Contact the package vendor for recommended integration configuration if the package documentation doesn't cover it.

Fix assignment and routing logic. Update lead assignment rules to have a fallback condition for records where the integration user is the creator. Add bypass conditions for auto-conversion triggers. Update territory rules to handle records without a full field set.

Grant the integration user missing permissions. Confirm that the integration user can run every Flow and Apex class that executes on sync. Check field-level security for every field in the failing record. Verify Record Type visibility. Grant Apex class access explicitly if it's not inherited from the profile.

Correct field mapping for read-only fields. If HubSpot's sync configuration includes a formula field, rollup field, or managed-package field, remove that field from the sync mapping. Salesforce will never accept a write to a read-only field regardless of permissions.

Common pitfalls

Validation rule added after integration setup. A Salesforce admin adds a rule to enforce data quality without knowing it will block the integration. The sync breaks on the next write with no connection to anything that changed in the integration itself.

Flow runs correctly for manual entry but fails for integration. Flows built for human users often assume fields are populated that an integration won't send. The Flow works perfectly in every manual test and breaks every time HubSpot touches the record.

Circular update loops. HubSpot updates a field → Salesforce Flow fires and updates a related field → HubSpot detects the change and updates again → loop continues until an error or governor limit stops it. These are some of the hardest failures to diagnose because the error location shifts on each iteration.

Managed package triggers with no bypass mechanism. Some packages don't expose bypass options. If the package vendor hasn't built an integration-friendly configuration path, the only resolution may be restructuring how HubSpot sends data to avoid triggering the package logic.

Debug logs not enabled before re-triggering. The most common diagnostic mistake,  attempting to diagnose a custom code error without a debug log active on the integration user. Without the log, you're guessing at which automation fired and why.

If you're seeing either of these errors and the resolution steps aren't clearing them, book a call with our team — we'll get into your sync logs and tell you exactly what's causing the failures.

Key Takeaways

Picklist mismatches and custom code errors share one characteristic: they fail silently. No alert, no dashboard warning, no rep notification. Records just stop moving — and your pipeline data quietly degrades until someone notices the numbers don't add up.

For picklist errors: always check API names, not just labels. Always audit automations writing to the field before marking the error resolved. A fix without an automation audit produces the same error on the next run.

For custom code errors: always enable debug logs on the integration user before diagnosing. The error message tells you what fired — the debug log tells you why. Without it, you're guessing.

Both error types require someone who understands both platforms well enough to trace the failure from the sync error back to its root cause in Salesforce's configuration. The fix is usually straightforward once you find it. Finding it is the hard part.

‍