HubSpot Integration — Troubleshooting

Token expired (HubSpot 401)

Symptom: Pipeline refreshes stop returning new data, or the test_hubspot MCP tool returns {"ok": false, "error": "Token expired or revoked"}. The integration status does not change — it still reads connected in FlowState, because a refresh failure never updates that field (see Permissions & scopes). There is no token_expired status and no automatic email — the hubspot.token_expired notification category exists but nothing ever triggers it today.

Cause: The OAuth refresh token has expired (HubSpot invalidates refresh tokens after approximately 6 months of inactivity) or was revoked by a HubSpot Super Admin.

Resolution:

1. Go to Settings → Integrations → HubSpot.
2. Click Disconnect, then Connect HubSpot again.
3. Authorize FlowState in the HubSpot OAuth consent screen.
4. Confirm the integration status shows Connected and, if you use them, re-run Provision properties.

The reconnect flow issues a new refresh token. Existing sync-state data and the 10 custom property values on deals are preserved.

Insufficient scopes (HubSpot 403)

Symptom: The integration connects but pipeline reads or property writes fail with a permissions error. The test_hubspot MCP tool returns a 403 response.

Cause: The HubSpot user who authorized FlowState did not have the necessary HubSpot permissions to grant all required scopes at authorization time, or a HubSpot admin has since restricted the app’s access.

Resolution:

1. Disconnect the current integration: Settings → Integrations → HubSpot → Disconnect.
2. Have a HubSpot Super Admin reconnect by clicking Connect HubSpot.
3. Confirm all 11 scopes are listed on the HubSpot consent screen before clicking Connect app — see Permissions & scopes for the full list.

If you see a scope missing from the consent screen, ensure the HubSpot user performing the authorization has Super Admin or App Marketplace Access in HubSpot.

Property provisioning failed

Symptom: After connecting, one or more of the 10 custom properties does not appear in HubSpot. The UI may show a warning during the connection wizard.

Cause (most common): A property with the same internal name already exists in your HubSpot portal but with a different type (for example, apn_mrr exists as a single-line text field instead of a number field).

Resolution:

1. In HubSpot, go to Settings → Properties → Search and look for the conflicting property name.
2. Either delete the conflicting property (if unused) or rename it.
3. In FlowState, go to Settings → Integrations → HubSpot and click Provision properties (there is no separate “Advanced” section), or call the provision_hubspot_properties MCP tool. Provisioning is an upsert, so re-running it is always safe.

The same card also has a Deprovision button that deletes all 10 APN properties from your HubSpot portal — it requires typing DELETE to confirm and is permanent. Use it only if you are removing the integration for good; it is unrelated to fixing a provisioning conflict.

If properties exist with the correct type but different display names or group assignments, the provisioner leaves them in place and treats them as already provisioned.

Webhook not firing (deals not syncing in real time)

Symptom: Deal changes in HubSpot are not triggering APN sync within the expected window.

FlowState waits a few minutes after a deal change before writing to AWS, so that editing several properties on the same deal produces one AWS write instead of one per property. The wait is five minutes in production. Only treat a change as missing once that window has passed.

Cause: The webhook subscription is shared across all connected portals (see Permissions & scopes), so a per-tenant loss is unusual — the more common causes are a HubSpot app reinstall on your side, or the change touching a property the webhook doesn’t subscribe to or that FlowState deliberately ignores as its own writeback (see Overview).

Resolution:

1. Confirm the change was to a property that actually triggers a sync (listed in overview.md) — a change to an AWS-mirrored property such as apn_sync_status never triggers one, by design.
2. Call the test_hubspot() MCP tool. A healthy response confirms your stored credentials are still valid. If the response is healthy but webhooks are still not firing for eligible properties, contact support — the shared webhook subscription may need to be re-registered.

Deal not syncing (APN sync not triggered)

Symptom: A deal has apn_sync_with_aws_enabled = true but APN sync never starts.

Causes and checks:

1. APN integration not connected. Go to Settings → Integrations → APN and confirm the integration is in the Connected state. If not, complete the APN onboarding wizard.
2. apn_sync_with_aws_enabled flag not persisted. Open the deal in HubSpot and confirm the apn_sync_with_aws_enabled property is set to true (not unknown). The property must be explicitly set; blank is treated as false.
3. Deal in an error state. Open FlowState’s deal list or call get_apn_sync_state_for_deal(hubspot_deal_id) to check the sync state. If apn_sync_status = error, read error_message in the response (or the FlowState card on the deal) for the specific failure.
4. Rate limit hit. If many deals were enabled for APN sync simultaneously, the APN write queue may be processing them in order. Check the rate-limit status via list_apn_sync_state().

Integration still shows “connected” after a HubSpot app reinstall, but nothing syncs

Symptom: A HubSpot admin uninstalled and reinstalled the FlowState app in HubSpot. FlowState’s integration status is unaffected by this on its own — it still reads connected — but pipeline fetches and APN sync silently fail because the old refresh token is now invalid (see the “Token expired” section above for why the status doesn’t reflect this).

Resolution: Disconnect and reconnect: Settings → Integrations → HubSpot → Disconnect, then Connect HubSpot. The reinstall invalidates the previous refresh token; reconnecting issues a fresh one. No deal data or APN sync-state data is lost.