If HubSpot’s Salesforce Sync Health shows a Restricted picklist value error, Salesforce rejected a value that HubSpot tried to write to a mapped picklist field. Start by identifying the exact record, property, Salesforce field, and value. Then check whether that value is allowed for the field and record type before you change the mapping or loosen the restriction.
A value can look correct on screen and still fail: the displayed label may differ from the internal value or Salesforce API name, the option may be inactive, or a record type may not allow it. Salesforce can also make a picklist dependent on another field, so an option that exists in the general list may not be valid in that record’s context.
Fast route: open the specific Sync Health error; record the object, affected property, mapped Salesforce field, paired record, and sync direction; compare the actual option values; check record-type and dependency rules; correct one cause; then resync one record and verify the result.
Confirm the error, field, and sync direction
In HubSpot, go to Settings → Integrations → Connected Apps → Salesforce → Data sync → Sync Health. Open the picklist error and inspect the affected-record details. HubSpot’s Salesforce integration sync-error guide treats “Restricted picklist value,” “Mismatched options,” and other errors as separate cases, and shows how to inspect, export, and resync affected records.
Before changing anything, note the object (such as Contact, Lead, Company/Account, or Deal/Opportunity), the HubSpot property, the Salesforce field, the affected record pair, and which system is attempting to write. For this restricted-value error, establish that HubSpot is trying to send a value to Salesforce. If you do not know which record or field failed, export or open the affected-record details first rather than changing a shared mapping based on a similar-looking contact.
| What Sync Health shows | What to check first | Keep it distinct from |
|---|---|---|
| Restricted picklist value | Does the exact Salesforce field and record type allow the value HubSpot is sending? | A value-set or record-type restriction |
| Mismatched options | Do the HubSpot internal option value and Salesforce picklist API value align? | A visible label that only looks the same |
| Salesforce duplicate rule | Which matching and duplicate rules affected the Salesforce record? | Picklist validation; see the duplicate-rule sync diagnostic |
| Owner resets after sync | Is the owner mapped to a matching active Salesforce user? | A picklist field; see the owner-sync diagnostic |
Compare the option values, not just the labels
Open the HubSpot property and Salesforce field used by the mapping. Compare the option the record actually contains with the current Salesforce picklist options. A label is what a person sees in a menu; an internal value or API name is what an integration may use. Salesforce documents API names as relevant to integrations, and HubSpot says mismatched picklist options may need the Salesforce option’s internal/API name aligned with the HubSpot property’s internal value.
Check for an option that was renamed, retired, or added in only one system. A renamed label does not necessarily mean that the underlying value changed in the same way. Do not edit an API name in production just to make two labels appear equal: Salesforce warns that API names can be referenced by integrations, formulas, and automation. Confirm the intended mapping with the field owner before changing an established value.
If this is a custom HubSpot dropdown mapped to a Salesforce picklist, compare the property’s internal option value with the Salesforce option’s API value as well as the visible labels. If the option is not present in HubSpot’s mapping list after a Salesforce change, refresh that mapping before deciding whether the record’s value itself is invalid.
Check record types and dependent picklists
A Salesforce picklist’s master value set is not always the full list that a specific record can use. A record type or business process can expose only selected values. Confirm the record’s actual type, then open the picklist settings for that type and verify the option is available there. Salesforce’s restricted-picklist error guidance for its Data Import Wizard identifies both an undefined value and a value unavailable to the record type as causes of that import error; do not assume every HubSpot message displays the same Salesforce error code.
Also check whether the field is dependent on a controlling picklist or checkbox. In that case, the selected value can be valid only for certain controlling values. Compare the two fields on the same Salesforce record and confirm that the controlling value is the one expected for the dependent option. A value appearing in the overall list is not enough to prove that it is valid for this record.
For the Salesforce error INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST, Salesforce’s documentation says the incoming value may be outside the defined value set or unavailable for the record type, and advises using API names rather than labels in the documented import scenario. Use the error text actually shown in HubSpot Sync Health as the primary evidence and check the Salesforce field configuration with an administrator.
Refresh the mapping, then choose a narrow repair
In HubSpot, open the Salesforce integration’s Data sync → object → Property mappings. Review the mapping and its sync rule. If a Salesforce picklist option was recently added, hover over the mapping and choose Refresh. HubSpot documents that refreshing checks for new Salesforce picklist options and can add them to the corresponding HubSpot dropdown property. Refreshing does not make a value valid for every Salesforce record type, or repair a wrong value already stored on a record.
| Finding | Narrow repair to evaluate | Before resync |
|---|---|---|
| Approved value is missing from the Salesforce field | Add the approved option to the correct field or shared value set, then make it available to the required record types. | Confirm the option is intended for this object and record type. |
| Option exists in Salesforce but not in the HubSpot dropdown | Refresh the mapping; add or align the corresponding HubSpot option if the property is editable. | Compare internal/API values, not just visible labels. |
| Value is not permitted by the record type or dependency | Make the approved option available for that record type, correct the controlling value, or choose the approved value for the record. | Preserve the organization’s record-type and validation rules. |
| Value is obsolete or outside policy | Change the affected record to a valid, documented equivalent, or stop mapping that property if it no longer belongs in the sync. | Do not silently discard meaning or bulk-rewrite records. |
| The organization intentionally wants values from integrations outside the defined set | Consider whether the restricted setting should be changed only after Salesforce and CRM owners review the data-quality impact. | Unrestricted picklists can accept values from APIs or other apps that the UI would not allow; set monitoring and ownership first. |
HubSpot lists turning off Salesforce’s “Restrict picklist to the values defined in the value set” setting as one possible resolution. That may fit an intentional data policy, but it broadens what can enter the field through integrations. If the restriction is there to keep values controlled, align the approved options and record-type availability instead of removing the guardrail just to clear the error.
Some standard HubSpot properties have fixed options. If a Salesforce field contains values that the corresponding HubSpot property cannot accept, HubSpot advises updating Salesforce to supported values, mapping to a different compatible property, or removing an incompatible custom mapping where possible. Do not add a second mapping to the same field as a workaround.
Resync one record and verify both sides
After the field options and mapping are corrected, return to the exact Sync Health error and resync one affected record. Check that the same HubSpot record is paired with the intended Salesforce Lead, Contact, Account, or Opportunity; that the chosen value arrived in the expected field; and that the specific error cleared. Also review nearby fields that share the mapping or automation path so a successful status does not hide an unintended overwrite.
If the single-record check succeeds, continue with a small affected subset and monitor Sync Health before applying a broader resync. If it fails again, capture the exact error details, field, option, object, record type, and direction. That evidence is more useful to a Salesforce administrator or HubSpot Support than a generic report that “the contact will not sync.”
Prevent the same picklist mismatch from returning
- Assign an owner for each mapped picklist and document which system controls the allowed values.
- When an option changes, update the Salesforce value set and record-type availability, then refresh the corresponding HubSpot mapping.
- Keep a field-value crosswalk for internal/API names when labels differ or one system uses a controlled translation.
- Test a new or changed option on one known record before allowing a wider sync or resync.
- Review Sync Health after CRM changes that affect record types, dependent fields, global value sets, or mapped properties.
Common questions
Should I turn off the restricted-picklist setting?
Only if the Salesforce and CRM owners decide the field should accept values supplied by integrations outside its defined set and put a data-quality control in place. HubSpot lists disabling the restriction as an option; Salesforce explains that the restriction prevents unapproved values from being added through APIs and other apps. For a controlled field, fixing the approved value set, record type, or mapped option is usually the narrower change.
Does this mean the Salesforce record is a duplicate?
No. A restricted-picklist error means a value was rejected under field rules. Salesforce duplicate-rule errors use a different sync-error category and require a separate check of matching and duplicate rules.
Will refreshing the HubSpot mapping fix every affected record?
No. Refreshing can expose newly added Salesforce options in the mapping. You may still need to make the option available for the record type, correct the affected record’s value, or address a dependent-field rule, then resync that record.
Sources and scope
This diagnostic uses the named HubSpot Sync Health error and official HubSpot and Salesforce documentation. Salesforce’s INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST example cited here is specifically about its Data Import Wizard; it is used to explain Salesforce value-set and record-type constraints, not to claim that HubSpot displays that exact code. Confirm interface labels and the current record-level error in the account before changing a production field.
Related reading: HubSpot’s Salesforce integration sync-error guide · HubSpot property mappings · Salesforce picklists for record types · Salesforce picklist API names.
How did this article land?
Choose one reaction. You can change it anytime.