Overview

This guide outlines the most common issues users encounter when connecting to or syncing data with HubSpot through Nexadata, along with recommended solutions. If you're experiencing errors, incomplete syncs, or missing objects, use the steps below to identify and resolve the problem quickly.

1. Connection Issues

OAuth Authentication Fails or Freezes

Symptoms:

The “Connect to HubSpot” button doesn’t complete the flow
The login screen never appears

Solutions:

Try completing the flow in an incognito/private window
Ensure you’re not blocking third-party cookies or cross-site tracking

HubSpot Workspace Doesn’t Appear

Symptoms:

You’ve authenticated, but no objects or properties are visible in the builder

Solutions:

Verify that the connected HubSpot user has appropriate permissions (at least CRM Admin or Super Admin role)
Reconnect using an account with broader access

Connection Shows as Disconnected

Symptoms:

HubSpot is listed as disconnected in Nexadata
You are unable to create new datasets or outputs

Solutions:

Click Reconnect to re-authenticate your session
Tokens may have expired. OAuth tokens automatically refresh, but manual reauth may be required after long periods of inactivity

2. Dataset Import Issues

Missing or Incomplete Properties

Symptoms:

Fields that exist in HubSpot aren’t showing in the Nexadata Dataset Builder

Solutions:

Ensure you selected the correct object (Contacts, Companies, etc.)
Reload the connection to fetch the latest schema
Custom properties may be tied to a specific record type. Please check HubSpot for field visibility settings.

Unsupported or Nested Fields

Symptoms:

Complex or nested fields cause errors during dataset creation

Solutions:

Nexadata automatically flattens nested HubSpot properties into a tabular format
If a property remains inaccessible, verify it’s properly defined in HubSpot and not tied to a custom object with missing associations

3. Output Sync Failures

Validation Errors During Sync

Symptoms:

Sync fails due to invalid field mappings or object schema mismatches

Solutions:

Double-check that each mapped Property aligns with the correct Object
Use Preview Schema to confirm available HubSpot fields
If using custom fields, ensure they are writable and not calculated

Missing Required Fields

Symptoms:

Error messages like “Missing Email” or “Primary Identifier not found”

Solutions:

HubSpot requires certain fields depending on object type:
- Contacts require email
- Companies require domain
- Deals often require a dealname
Ensure these fields are present in your dataset and correctly mapped

Improper Object Handling Rules

Symptoms:

Sync does not update or insert records as expected

Solutions:

Confirm the correct Action is selected in the Output Builder:
- Use Upsert when you want to update or insert based on available identifiers
- Use Update only when records already exist in HubSpot
If using alternate IDs or custom keys, verify those values exist in HubSpot prior to sync

4. General Tips

Sync during off-peak hours if you're pushing large volumes of data
Always preview your mapping before syncing to confirm alignment
Refer to HubSpot's object and property documentation for additional schema rules