Troubleshooting HubSpot integration and sync issues requires a systematic approach to identify and resolve common problems that prevent data from flowing correctly between HubSpot and connected platforms like Salesforce, Zoom, or other third-party tools. Most sync failures stem from configuration errors, permission mismatches, API limitations, or data inconsistencies between systems. The most critical first steps involve checking the Sync Health dashboard in HubSpot, verifying user permissions, and ensuring property mappings align between integrated platforms. For Salesforce integrations—the most frequently discussed scenario—errors often relate to API call limits, duplicate records, picklist mismatches, or insufficient access rights for the integration user.

Key findings from the sources include:

• Sync Health tab is the primary tool for diagnosing errors, showing affected records and error types ^[2][3]
• API call limits can halt syncs entirely; monitor usage in HubSpot’s Connected Apps settings ^[2][8]
• Permission issues account for ~30% of sync failures, requiring admin-level access reviews in both HubSpot and the connected platform ^[2][9]
• Property mapping errors (e.g., mismatched picklist values or missing required fields) are among the top causes of failed syncs ^[3][6]

Core Troubleshooting Strategies for HubSpot Sync Issues

Diagnosing Sync Errors Using HubSpot’s Built-in Tools

HubSpot provides dedicated tools to identify and categorize sync errors, which should be the starting point for any troubleshooting process. The Sync Health tab (located under *Integrations > Connected Apps > [Integration Name]*) displays real-time error logs, affected records, and error types. This dashboard allows users to filter errors by category (e.g., duplicates, permissions, or custom code) and take bulk actions like resyncing up to 100 records at once ^[2][3].

To effectively use these tools:

• Check the error type classification: HubSpot categorizes errors into eight primary types, each requiring different resolutions:
• Associations: Records fail to sync due to missing links between objects (e.g., a contact not associated with a company) ^[2]
• Custom Code: Errors triggered by Salesforce validation rules or workflows (requires Salesforce admin collaboration) ^[2]
• Duplicates: Conflicts when identical records exist in both systems (use HubSpot’s deduplication tools) ^[3]
• Permissions: The integration user lacks "read/write" access in Salesforce or HubSpot (verify in *Setup > Users > Permission Sets*) ^[2]
• Picklists: Value discrepancies between HubSpot and Salesforce dropdown fields (e.g., "Customer" in HubSpot vs. "Client" in Salesforce) ^[3]
• Property Mappings: Fields are mapped incorrectly or lack matching data types (e.g., text vs. number) ^[6]
• Property Values: Invalid entries (e.g., emails without "@" symbols or dates in wrong formats) ^[2]
• Other: Unclassified errors requiring HubSpot Support intervention ^[3]
• Set up error notifications: Configure alerts in the Sync Health tab to receive emails when new errors occur, enabling proactive management ^[2].
• Use the "Resync" feature: For bulk errors, select up to 100 records and click Resync to retry synchronization. Note that this may fail again if the root cause (e.g., permission issue) persists ^[2].

For Zoom integrations, sync problems often trace back to permission gaps or unauthenticated users. If Zoom call recordings fail to sync, verify that:

• All users have both Zoom and HubSpot accounts linked with proper permissions ^[7].
• The integration is reauthorized in *HubSpot Settings > Integrations > Zoom* (expired tokens are a common issue) ^[7].
• Meeting attendees logged into Zoom with their registered accounts (anonymous attendees won’t sync) ^[7].

Resolving Common Integration-Specific Issues

Salesforce Integration Problems

Salesforce sync errors dominate HubSpot integration discussions, with API limits, lifecycle stage mismatches, and property conflicts as the top culprits. To resolve these:

1. API Call Limits: - HubSpot’s Salesforce integration allows 50,000 API calls per day (shared across all connected apps). Exceeding this limit pauses syncs until the next day ^[2]. - Check usage in *HubSpot Settings > Integrations > Connected Apps > Salesforce > API Usage*. If near the limit: - Reduce sync frequency for non-critical objects (e.g., sync contacts hourly instead of real-time) ^[8]. - Prioritize high-value fields to minimize unnecessary API calls ^[4].

1. Lifecycle Stage Sync Failures: - If lifecycle stages stop syncing after recreation (e.g., deleting and recreating a "Customer" stage), the issue stems from mismatched Internal IDs between HubSpot and Salesforce ^[6]. - Solution: Update the Salesforce API value to match HubSpot’s new Internal Value (found in *HubSpot Settings > Properties > [Lifecycle Stage Property]*). Alternatively, create a new Salesforce picklist value to remap ^[6].

1. Property Mapping Errors: - Picklist mismatches: Ensure every HubSpot picklist value has a corresponding option in Salesforce. For example, if HubSpot has "Lead," "MQL," and "SQL," Salesforce must include identical labels ^[3]. - Required field gaps: Salesforce may require fields (e.g., "Company Name") that HubSpot marks as optional. Populate all Salesforce-mandated fields before syncing ^[1]. - Data type conflicts: A HubSpot text field cannot map to a Salesforce number field. Recreate properties with matching types in both systems ^[2].

1. Duplicate Records: - HubSpot and Salesforce may create duplicates if: - The same email address exists in both systems but isn’t linked ^[3]. - A contact is manually created in Salesforce while HubSpot’s automation generates a duplicate ^[8]. - Resolution: - Use HubSpot’s Merge tool to combine duplicate contacts/companies ^[3]. - Enable Salesforce’s Duplicate Management rules to block duplicate creation ^[8].

Third-Party Integration Issues (e.g., Zoom, Referral Factory)

For non-Salesforce integrations, focus on:

• Authentication failures: Reauthorize the integration in HubSpot’s Connected Apps section. For Zoom, this involves reconnecting the OAuth token ^[7][9].
• Missing properties: If a HubSpot property doesn’t appear in the third-party tool:
• Disconnect and reconnect the integration to refresh field mappings ^[9].
• Ensure the property is marked as "visible" in HubSpot (*Settings > Properties > [Property Name] > Visibility*) ^[9].
• Permission conflicts: Grant the integration user full read/write access in both HubSpot and the third-party platform. For Referral Factory, this includes permissions for contacts, deals, and custom objects ^[9].

Advanced Troubleshooting Steps

If errors persist after basic fixes:

• Review integration logs: Tools like Planhat’s query tool or HubSpot’s API logs (under *Settings > Integrations > [Integration] > Logs*) reveal detailed sync attempts and failures ^[5].
• Test with a single record: Manually sync one record to isolate whether the issue is system-wide or record-specific ^[5].
• Contact HubSpot Support: For "Other" error types or unresolved issues, provide:
• Screenshots of the Sync Health tab.
• Steps taken to resolve the error.
• The HubSpot Account ID and Integration ID (found in the URL when viewing the integration) ^[3].