This guide brings together the most common issues during OAuth, Field Mapping, imports, and exports.
HubSpot does not complete the connection
Check the following, in this order:
The account is HubSpot Enterprise.
Authorization is performed by a Super Admin.
You selected the correct portal.
The app is not blocked in Settings > Integrations > Connected Apps.
All requested scopes are still available.
If the HubSpot tab closes or you return to Enginy without confirmation, reload Integrations and check the card. Use Reconnect if it is still disconnected.
The integration shows missing scopes
HubSpot may have revoked a permission, or the portal may not support one of the required scopes.
Ask a Super Admin to use Reconnect and accept all permissions. If HubSpot does not allow you to continue, check the account plan and the scopes shown on the OAuth screen.
What Field Mapping icons mean
The blue check means the option is selected.
The yellow warning lets you save, but warns of a possible incompatibility.
The red icon means the option is disabled, usually because the property is read-only or cannot be used in that context.
A blue check does not validate every value that will be sent. A type mismatch usually appears as a yellow warning.
Warning with an Enumeration field
HubSpot validates the internal value of each option, not only the visible label.
For example, an option may display as "Active customer" and have active_customer as its internal value. Enginy must send active_customer exactly, respecting uppercase, lowercase, and characters.
If the value does not exist, HubSpot may return 400 VALIDATION_ERROR for that record.
Warning with dates
Match dates with HubSpot Date or DateTime properties.
For manual values, use one of these formats:
dd/MM/yyyydd-MM-yyyyyyyy-MM-dd
Avoid mapping a date to a text property unless you want to save the value as text and accept losing HubSpot's date behavior.
Multi-select fields
Separate multiple values with semicolons, for example value_a;value_b;value_c.
Each item must match the internal value of a HubSpot option. Spaces or visible labels that do not match can cause a validation error.
Read-only properties
Calculated or HubSpot-managed properties may be read-only. Enginy shows them as disabled and cannot write to them.
Choose an editable property or create a compatible custom property in HubSpot. Then reopen Configure to refresh the field list.
The export creates a duplicate
Review Contact Identifier or Company Identifier:
Professional email, LinkedIn URL, and name with Company for Contacts.
Domain, Domain or Company Name, or Custom Mapping for Companies.
Unique and stable values for Custom Mapping.
If HubSpot already contains several equivalent records, resolve the duplicate there first. Enginy does not automatically merge an ambiguous match.
Associations have disappeared from a Contact
Review Association Type in the export or workflow. The replace option removes previous associations before creating the new one.
Use append if you want to keep them all, or primary if you want to set a primary one without applying the full replacement.
A list import does not start
HubSpot's Exports API only supports one simultaneous export and 30 exports per rolling 24-hour window. Wait for the previous operation to finish and try again.
Also check that the list still exists and that the connection still has crm.lists.read and crm.export.
Prepare a support case
Include:
Affected HubSpot portal.
List or workflow name.
Approximate time of the error.
Contact or Company ID in Enginy and HubSpot.
Screenshot of the full message.
Sync direction and Association Type used.
Do not send passwords or OAuth tokens.