How to Debug HubSpot Association CDC Boost Setup¶

Prerequisites¶

HubSpot access token for the client's portal
Access to the base schema (query DB or export from admin)
jq installed locally

Steps¶

1. Get the rollup fields that exist in HubSpot¶

For each standard object, query the HubSpot Properties API and filter for sync_associations_ prefix:

TOKEN="<hubspot_access_token>"

echo "=== Companies ==="
curl -s "https://api.hubapi.com/crm/v3/properties/companies" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '[.results[] | select(.label | startswith("sync_associations_companies"))] | .[].label'

echo "=== Contacts ==="
curl -s "https://api.hubapi.com/crm/v3/properties/contacts" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '[.results[] | select(.label | startswith("sync_associations_contacts"))] | .[].label'

echo "=== Deals ==="
curl -s "https://api.hubapi.com/crm/v3/properties/deals" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '[.results[] | select(.label | startswith("sync_associations_deals"))] | .[].label'

2. Get what Stacksync detected¶

Export the base schema and search for supports_roll_up and rollup_field_labels in each association table's table_options. You're looking for:

supports_roll_up: true or false
rollup_field_labels: list of detected labels
rollup_fields_object_id: which object the rollup fields are on (added in PR #1507)

3. Compare¶

For each association table, check:

Check	What to look for
`supports_roll_up` is `true`?	If `false` but rollup fields exist in HubSpot, the sync needs to be re-saved
All labels present?	New labels added after last sync save won't be detected until re-save
`rollup_fields_object_id` correct?	Should be the alphabetically first object (e.g., `companies` for companies-contacts)

4. If mismatched, re-save the sync¶

Stop the sync → Edit → Click Next through all steps → Save → Start.

This re-runs setup.py which queries HubSpot for rollup fields and updates table_options.

5. Verify after re-save¶

Export the base schema again and confirm supports_roll_up is now true and rollup_field_labels is populated for the expected tables.

Gotchas¶

Rollup fields are on the alphabetically first object. Docs tell users to create them on companies (not contacts) for companies-contacts. Our code sorts alphabetically to match (PR #1507).
Engagement objects can never use CDC Boost. Calls, emails, meetings, notes, tasks, communications, postal_mail — HubSpot doesn't allow rollup properties on them. supports_roll_up will always be false.
Custom objects use numeric IDs. The prefix would be something like sync_associations_companies_2-4029593_label_none — impractical for users to create. Not currently documented or recommended.
Token expiry. HubSpot access tokens expire quickly. If the curl returns null/error, get a fresh token from the credentials store.
The sync must be re-saved after creating new rollup fields. Rollup fields are only detected during the setup phase, which runs on save.