Troubleshooting the HubSpot integration

Available on: Platform > Integrations > HubSpot > History
Who can do it: Admin
Module: Platform

---

Always start with the History

Almost every sync problem has a record in the History tab, inside the integration. That is where the diagnosis comes from.

1. In Platform > Integrations > HubSpot, click Configure and open the History tab

2. Search by the contact's name, phone number, or ID; the field also accepts conversation IDs and HubSpot IDs

3. Filter by Status: Failed or Partial to see only what went wrong

4. Click the event to open the details panel

In the details, the Error section shows the cause in plain language with the HubSpot code next to it, plus the original text returned by HubSpot.

Fields stopped going to HubSpot, with no visible error

What you see: a contact was updated in Nuvia, nothing changed in HubSpot, and no message appeared on screen.

Most common cause: a dropdown or multiple choice field with a value that does not exactly match the property's options in HubSpot. A difference in capitalization, accents, or spaces is enough. When this happens, HubSpot rejects the entire record; all the other fields for that contact are not saved either.

How to confirm: in the History, the event appears with status Failed or Partial and the message “The value sent is not one of the options accepted by property X in HubSpot.”

How to fix it:

1. Open the property in HubSpot and copy the exact text of the options

2. In Nuvia, adjust the field options so they are identical

3. Change a test contact and confirm in the History that the status is back to Success

The same contact became two records in HubSpot

Cause: before creating a contact, Nuvia looks for the record in HubSpot by phone number and by email. The phone search covers the number in international format, with and without a space after +55. If the number is stored in HubSpot in another format, the search does not find it and a new contact is created.

Formats the search does not find:

• (11) 99999-9999 with parentheses and a hyphen

• 11999999999 without the country code

• A number with the ninth digit on one side and without it on the other

• Numbers from other countries stored in local format

How to fix it:

1. Standardize the phone numbers in HubSpot to international format (+5511999999999)

2. Fill in the contacts' email in Nuvia whenever possible; when there is an email, it takes priority over the phone number in the search and the matching is much more accurate

3. Merge the duplicate records in HubSpot itself

The same contact showed up with two deals in HubSpot

Cause: in Nuvia, a contact is unique by phone number within the account; talking to two different inboxes does not duplicate the contact. The deal, on the other hand, is linked to the conversation. Before creating a new deal, Nuvia looks in HubSpot for a deal already associated with that contact in the same pipeline and reuses that record. In other words: two conversations from the same contact mapped to the same pipeline share the same deal.

Two deals appear when:

• The conversations are mapped to different pipelines in HubSpot

• The contact was not yet linked to a HubSpot record when the deal was created

• The lookup of deals associated with the contact failed at that moment

How to fix it: in the Funnels tab, review which stages have the Deal toggle on and which HubSpot pipelines they point to. If the goal is a single deal per customer, keep deal creation in a single stage and a single pipeline. Deals that are already duplicated need to be merged in HubSpot.

HubSpot contacts are not reaching Nuvia

Likely cause: the contact's phone number in HubSpot has no country code or is in a format Nuvia cannot interpret. Contacts with an invalid phone number are discarded on the way in, and this does not create a record in the History.

How to fix it:

1. Open the Advanced tab and find Phone settings

2. Select the default country code for your operation (for example, +55 - Brasil). The setting is saved automatically when you select it

3. Check that the contact has a phone number filled in in HubSpot; contacts without a phone number are not created in Nuvia

How the default country code works:

• It only applies to numbers that come from HubSpot without a country code

• It is only applied when the number has 11 digits or fewer and does not already start with that country code

• Numbers that already arrive in international format (with +) are not changed

• For Brazil, an 8-digit number starting with 6, 7, 8, or 9 gets the ninth digit added automatically

• Numbers with fewer than 8 digits are discarded

Leaving the None (detect automatically) option makes Nuvia try to guess the country from the first digits of the number, which can be wrong for numbers without a country code. If your operation is mostly in Brazil, set +55 explicitly.

The deal does not change stages in HubSpot

Check in this order:

1. Is there a mapping? In the Funnels tab, confirm there is a row linking that funnel stage to the HubSpot deal stage

2. Is the deal closed? Nuvia does not move a deal already marked as won or lost in HubSpot

3. Is the stage before the current one? Nuvia does not move the deal backward. If the deal is already at a later stage, the move is ignored

4. Is the conversation linked to a deal? Without a link, there is nothing to move

Items 2 and 3 are intentional safeguards; in these cases the deal stays as it is and the event is recorded in the History without an error.

The conversation does not move forward when I move the deal in HubSpot

Cause: by default, each mapping row is Nuvia → HubSpot, meaning outbound only.

How to fix it: in the Funnels tab, change the Direction column for that stage to ↔ Bidirectional (the same as turning on Hubspot → Nuvia for that row). The conversation also needs to be linked to a deal.

HubSpot errors and what to do

Frequently asked questions