When a record does not sync, pressing resync again gives you little information unless you know why the previous attempt failed. To investigate HubSpot Salesforce sync errors, start with one affected record, its intended destination and the exact error. Then check whether the problem is a record-specific rejection, a configuration mismatch or a wider integration interruption.
TLDR: Capture the error and both record identities. Check sync scope, mapping, required values, picklists, integration-user access and API availability. Have the responsible administrator approve the correction, then retest a defined set and verify the destination values. Do not start by reinstalling the integration or widening permissions.
Product documentation checked August 29, 2026. The error worksheet is fictional and the sequence is our recommended diagnostic process. Confirm the active integration and account configuration before making changes.
HubSpot documents Salesforce integration errors under the connected app's Data sync and Sync Health views. The error cards identify affected records and provide options to investigate them. Start with the exact message and record evidence available there. HubSpot: Salesforce sync errors.
We recommend saving a sanitized incident note with the time observed, object type, HubSpot record reference, Salesforce record reference and intended operation. Keep credentials, authentication tokens and unnecessary customer data out of the note.
If you are still deciding which systems to connect, our HubSpot integration overview covers the broader landscape. This checklist is for diagnosing an existing Salesforce sync.
Before changing a field, write down the expected behavior. Which object should move in which direction? Which record should it match? Which setting or approved business rule makes this record eligible?
Review the installed integration's actual object settings and mappings. A missing destination record and an incorrect field value are different symptoms. Keep them separate in the diagnostic note so a mapping adjustment is not used to solve an identity problem.
We recommend comparing an affected record with a similar record that behaves as expected. Look for a meaningful difference in the approved scope, identity, field values or owner. Do not copy the working record's values into the failing record simply to make the error disappear.
HubSpot documents that a Salesforce organization API limit can slow or pause sync activity. Its suspension guidance also covers missing object or field permissions, storage limits and organization availability. Check the actual suspension message before assuming the error is in the contact data. HubSpot: Salesforce suspension errors.
If many unrelated records stopped at the same time, ask the integration owner to review the account-wide condition. If one field or record type repeatedly fails, narrow the review to that shared dependency. These are diagnostic hypotheses, not proof of a cause.
Do not raise API allocation or change a Salesforce permission just because it appears in a troubleshooting list. Have the authorized administrator confirm the constraint and approve a specific response.
HubSpot groups sync errors into categories including associations, custom code, duplicates, permissions and picklists. Use the reported category to guide your next check rather than applying every possible fix. HubSpot: error categories.
The following table is our recommended review sequence, not a list of guaranteed causes.
| Symptom or error theme | Evidence to inspect first | Safe next step |
|---|---|---|
| Record is absent from the expected destination | Intended sync direction, eligibility and matching identity | Document which condition is unmet before changing scope |
| Required field or validation rejection | Exact field, submitted value and destination rule | Ask the data owner for the correct value or an approved rule change |
| Picklist mismatch | Source value, destination option and current mapping | Review the translation with the field owner |
| Permission error | Integration user, affected object and field | Ask the administrator to verify the precise missing access |
| Duplicate or identity conflict | Both systems' stable record references | Route the identity decision for review before any merge or deletion |
| Association failure | Intended related records and relationship | Verify the relationship and whether the connector supports it |
| Broad suspension or capacity issue | Current suspension message and platform availability | Resolve the confirmed system condition before retrying batches |
Treat validation rules and permissions as controls with owners. Disabling them globally to clear a queue can create a second problem that is harder to trace than the original sync failure.
The following fictional diagnostic worksheet illustrates three records. The error descriptions are paraphrased examples, not copied production messages or real Salesforce records.
| Test reference | Observation before review | Approved correction to test | Acceptance evidence |
|---|---|---|---|
| TEST-SF-01 | Territory value is rejected | Use the field owner's approved translation | Correct territory appears on the intended destination record |
| TEST-SF-02 | Integration user lacks access to a required field | Administrator reviews the precise access requirement | Intended operation completes without broader access changes |
| TEST-SF-03 | Two candidate records could match one contact | Identity owner selects the correct relationship | Both stable references match the approved identity decision |
Write the expected result before executing the correction. Keep the prior value and mapping version in your approved internal record. Then have an authorized operator make only the reviewed change.
A disappearing error is useful, but it does not prove the resulting data is correct. Inspect the destination record, relevant field and association. Confirm that the fix did not unexpectedly change a different field or create another record.
HubSpot's sync-error guidance provides a Resync action for selected errors after their causes are resolved. Use that capability with the approved test scope and inspect the resulting records. HubSpot: review and resync errors.
We recommend recording each test's prior error, approved change, retry time and observed result. If the error returns, preserve the new evidence rather than repeatedly resubmitting the same record.
For a batch correction, reconcile the intended population. Every record should have a disposition such as verified, still failing or intentionally excluded. Do not close the task because the visible queue is smaller without explaining the remaining records.
Escalate when the error is unclear, the correct identity is disputed, the required access is uncertain, or a correction would affect a broad population. Provide the integration owner or support team with a sanitized reproduction and the exact observed message.
We recommend including what you expected, what happened, when it happened, what changed recently and which tests you already performed. Do not send raw credentials or an unrestricted customer export as troubleshooting evidence.
If other portal issues appear during the review, keep them in a separate backlog. Our guide to common HubSpot issues can help frame that wider investigation without expanding the current correction unnecessarily.
A useful Salesforce sync error note should distinguish evidence from interpretation. “The destination territory is unchanged” is an observation. “The mapping is wrong” is a hypothesis until you inspect the submitted value, mapping and destination rule. Keeping those statements separate helps the next authorized responder reproduce the issue.
For the fictional TEST-SF-01 record above, retain the source territory reference and the destination reference before changing anything. Have the field owner approve the translation. After the controlled resync, inspect that same destination record and check that the intended value arrived. Also check that a second record was not created unexpectedly.
If the evidence points to a Salesforce rule, flow or access decision, give the Salesforce administrator the exact operation and sanitized failure. Explain the approved business outcome and the correction already tested. Do not prescribe a global rule disablement because a local sync request was rejected.
If the evidence points to HubSpot scope or mapping, give the HubSpot administrator the same source and destination references. The goal is a shared reproduction, not a ticket that each team can close by saying its own platform is available. Keep unresolved identity decisions with the business owner who can determine the intended record.
For the native HubSpot Salesforce integration, open Settings, Integrations, Connected Apps, Salesforce, then Data sync and the relevant object's Property mappings. HubSpot requires compatible HubSpot property and Salesforce field types. Inspect the selected sync rule as well as the field pair: the rule determines which system's value can win. HubSpot: field mappings and sync rules.
We recommend comparing the exact property value, field types and intended direction on one record before changing a mapping. Check custom fields separately from the required field that appears in the error. If a two-way sync is intended, test an authorized change from each side and confirm the result in the other system. Do not assume that a successful update in one direction proves the reverse path.
For a Salesforce picklist error, record the rejected source value and the destination option the business intended. Ask the Salesforce admin to inspect the applicable field configuration, restricted picklist and record types, where relevant to the reported error. A visually similar label is not evidence that the submitted value is accepted.
A mapping mismatch needs a field-level decision. Keep the HubSpot property, Salesforce field, source value and approved translation in the same note. Recheck the actual destination property value after correction rather than closing the issue because the error type changed.
HubSpot's current documentation calls these inclusion segments. They control eligible records and have documented first-sync exceptions. Selecting an inclusion segment does not itself trigger a sync. Check the actual criteria and object configuration when investigating a missing record. HubSpot: inclusion segments and sync behavior.
For a contact expected to qualify because of its lifecycle stage, inspect the saved stage and the inclusion list criteria together. Preserve the evidence before editing either. Expanding the segment to all contacts may remove the symptom while sending records the business never intended to sync.
When Salesforce contacts or Salesforce accounts appear to have competing matches, retain both systems' stable references. Ask the identity owner to determine the intended pairing. Review any reported duplicate rules with the Salesforce admin; do not merge or delete records merely to clear the queue.
For access failures, identify the integration user actually executing the request. If your team uses a dedicated integration user, review that user's precise object and field access, including relevant permission sets. The ability of other Salesforce users to edit a record does not prove that the integration user can perform the same operation. Give the administrator the required operation and error, not a request for unrestricted access.
Keep the time of the last known successful sync, the first observed failure and any relevant batch activity in the incident note. Ask the integration owner to inspect Salesforce API calls and the confirmed capacity message. An API allocation decision belongs with the administrator who can see other applications sharing that capacity. After the constraint is addressed, verify the approved sample in both HubSpot and Salesforce before expanding the retry.
We recommend identifying the exact failure before considering a reinstall. Review the current settings and dependencies, and obtain approval for any action that could interrupt the existing integration.
No. Ask the authorized administrator to identify the object, field and operation involved. Review the specific access requirement instead of using broad access as a default repair.
Verify the destination record, expected values and associations. Record the observed result and check the approved sample before closing the issue.
Use the minimum evidence needed to explain the issue, following your organization's approved support and privacy process. Prefer sanitized references and omit credentials or authentication tokens.
Our HubSpot operations services can help you review mappings, dependencies and the evidence needed to accept a correction.
If the cause remains uncertain, talk with Selworthy with the sanitized error, expected behavior and affected record type. That is a useful starting point for a scoped diagnostic review.