Diagnose and fix the most frequent errors that occur when Cotonity connects to HubSpot, including OAuth failures, permission scopes, and portal ID mismatches.
OAuth connection setup errors
When you first connect Cotonity to HubSpot, the OAuth handshake must complete without interruption. If you see an 'Authorization failed' error immediately after clicking Connect, the most likely cause is that you closed the HubSpot authorization popup before granting access, or a browser extension blocked the popup from opening. Disable popup blockers for app.cotonity.com, then retry the connection from Settings > Connections > HubSpot. If the error persists, try connecting in an incognito window to rule out cached session data from a previous HubSpot login conflicting with the authorization flow.
Insufficient permission scopes
Cotonity requires a specific set of HubSpot OAuth scopes to read contacts, companies, deals, and timeline events. If your HubSpot account has scope restrictions enforced by a super admin, the connection may succeed but specific workflow steps will return a 403 Forbidden error at runtime. To check which scopes were granted, go to Settings > Connections > HubSpot and click 'View granted scopes'. Compare this list to the required scopes listed in our HubSpot integration reference. If scopes are missing, disconnect and reconnect while ensuring you are logged in as a HubSpot super admin who can approve all requested permissions.
Portal ID mismatch errors
If Cotonity is configured to target a specific HubSpot portal ID but the connected OAuth token belongs to a different portal, workflow steps that write data will fail with a 'Portal not found' or 'Object not found' error. This commonly happens when a team member connects their personal HubSpot sandbox instead of the production portal. Check the portal ID shown in Settings > Connections > HubSpot and compare it against the Hub ID visible in the top-right corner of your HubSpot account settings. If they do not match, disconnect the current connection and reconnect using an account authenticated against the correct portal.
Reconnecting after a token expiry
HubSpot OAuth tokens issued to Cotonity are long-lived, but they expire if the authorizing user's HubSpot account is deactivated, if a super admin revokes the app's access, or if the connected HubSpot portal is suspended. When this happens, all agents that use the HubSpot connection will begin failing with a 401 Unauthorized error. The fix is straightforward: navigate to Settings > Connections > HubSpot, click 'Reconnect', and complete the OAuth flow again. After reconnecting, the new token is automatically applied to all existing workflows — no individual agent reconfiguration is needed.