HubSpot Integration Troubleshooting
This article covers the most common issues administrators encounter with the HubSpot integration and how to resolve them. If your issue is not listed here, contact Magentrix Support with the relevant event log entries.
Authorization Has Been Revoked
Symptom: Sync jobs fail with an authentication error, or the integration stops syncing after a HubSpot administrator removed the connected app or revoked the authorizing user's access.
Cause: Magentrix uses a refresh token captured during the original OAuth authorization. If the connected app is uninstalled in HubSpot, or if the user who authorized it loses access, the refresh token can no longer be exchanged for a new access token.
Resolution: Contact your Magentrix account team to request a new authorization link. Repeat the steps in Authorizing HubSpot for Your Magentrix Portal.
HubSpot API Rate Limits Reached
Symptom: Scheduled Jobs report HTTP 429 errors or partial sync results during periods of heavy activity.
Cause: HubSpot enforces API rate limits on every connected app. The exact limit depends on your HubSpot subscription tier. Magentrix already throttles requests when HubSpot signals that the rate limit is nearly exhausted, but bursts of activity can still trip the limit.
Resolution:
- Reduce the Scheduled Job frequency for HubSpot syncs (see Scheduled Jobs).
- Reduce the number of mapped fields for entities that change infrequently.
- If you require higher API throughput, review your HubSpot subscription tier with HubSpot.
Picklist Values Do Not Match
Symptom: A HubSpot picklist field syncs values that look like raw option keys instead of the expected labels, or specific values fail to sync.
Cause: HubSpot enumeration properties expose option internal values through the API, not the display labels. If a Magentrix picklist option uses a different value from the HubSpot internal value, the sync cannot match them.
Resolution:
- From the HubSpot Integration page, click Refresh on the affected entity. This re-imports the picklist options from HubSpot and aligns them automatically.
- If a value remains unmatched, edit the Magentrix picklist directly and align the option value to the HubSpot internal value.
Owner Is Not Mapped
Symptom: Records arriving from HubSpot are all assigned to the Default Owner instead of the HubSpot owner's Magentrix counterpart.
Cause: The HubSpot owner does not yet exist as a Magentrix user, or the HubSpot User ID has not been populated on the matching Magentrix user.
Resolution:
- Ensure the HubSpot owner has been added as an Employee user in Magentrix.
- From the HubSpot Integration page, open the actions menu and click Connect Owners. Magentrix re-matches HubSpot owners to Magentrix users by populating the HubSpot User ID field on the User entity.
Associations Are Missing After Sync
Symptom: Imported Contacts do not show their parent Company, or imported Deals do not show their associated Contacts.
Cause: Associations require both the parent and child records to exist in Magentrix. If the parent has not yet been imported when the child is processed, the association is skipped on that pass.
Resolution: Allow the next Scheduled Job runs to complete in order (Companies, Contacts, Deals). Subsequent runs reconcile any associations that were skipped on earlier passes.
Surviving Record Missing After a HubSpot Merge
Symptom: A Company or Contact merge appeared to succeed in HubSpot, but the surviving record is missing or stale in Magentrix.
Cause: The merge was not yet processed by the next Scheduled Job, or an underlying error (validation rule, foreign-key constraint) prevented part of the merge from completing.
Resolution:
- Wait for the next Scheduled Job run, or trigger a manual sync.
- Check the system event log for entries related to merge processing. See HubSpot Object Merge Handling for details on how merges are processed.
<< HubSpot Object Merge Handling