Connection & OAuth Issues

This page covers common issues with connecting HubSpot portals to JetStack AI and managing OAuth authentication. Each entry follows a Symptom / Cause / Solution format.

OAuth Flow Issues

OAuth Flow Fails

Symptom: Clicking “Connect Portal” opens the HubSpot OAuth screen, but the flow does not complete. You may see a blank page, an error message, or get redirected back to JetStack AI without a successful connection.

Cause: OAuth flow failures can result from:

• Browser pop-up blocker preventing the OAuth window from opening
• Ad blocker or privacy extension intercepting the OAuth redirect
• Browser cookies disabled or restricted for third-party domains
• HubSpot is experiencing downtime on their OAuth service
• Your JetStack AI session expired during the OAuth flow
• The OAuth redirect URL was blocked by a corporate firewall or proxy

Solution:

1. Disable pop-up blockers for app.hubspot.com and jetstack.ai
2. Disable ad blockers and privacy extensions temporarily during the connection
3. Ensure third-party cookies are allowed, or add exceptions for hubspot.com and jetstack.ai
4. Try the connection in an incognito/private browser window
5. Log out of JetStack AI and log back in, then retry the connection
6. If you are behind a corporate firewall, ensure app.hubspot.com, api.hubspot.com, and api.jetstack.ai are allowlisted
7. Check HubSpot’s status page for any ongoing service disruptions

OAuth Window Closes Immediately

Symptom: The HubSpot OAuth authorization window opens briefly and then closes without showing the permission approval screen.

Cause: This typically happens when:

• You are already signed into HubSpot with an account that does not have Super Admin access to the target portal
• Multiple HubSpot sessions are conflicting in the browser
• The OAuth state parameter expired (the connection was initiated too long ago)

Solution:

1. Sign out of all HubSpot accounts in your browser
2. Sign into the specific HubSpot portal you want to connect using a Super Admin account
3. Retry the connection from JetStack AI immediately after signing in
4. If you manage multiple HubSpot accounts, use separate browser profiles to avoid session conflicts

Insufficient Scopes

Symptom: The portal connects successfully, but certain operations fail with “Insufficient scopes” or “Missing required scope.”

Cause: During the OAuth flow, HubSpot shows a list of permissions (scopes) that the app is requesting. If certain scopes are declined or if HubSpot’s API requires a scope that was not originally requested, operations that depend on those scopes will fail. This can also happen when:

• JetStack AI added new features requiring additional scopes after the initial connection
• A HubSpot admin restricted the app’s permissions after connection
• The portal was connected with an audit-only connection type but is being used for implementations

Solution:

1. Navigate to Account > Portals in the JetStack AI dashboard
2. Click the affected portal and check its connection type and status
3. Click “Reconnect” to re-initiate the OAuth flow with the latest required scopes
4. During the OAuth flow, ensure you approve all requested permissions
5. If you only need audit capabilities, an audit connection type is sufficient. For implementations, use the implementation or combined connection type.
6. See OAuth Connection Flow for details on what each scope enables

Scope Approval Not Shown

Symptom: The OAuth flow completes without showing a scope approval screen, but the connection has limited permissions.

Cause: HubSpot may auto-approve scopes if the app was previously connected and scopes have not changed. However, if the previously approved scopes were a subset of what is now required, the auto-approval may skip the new scopes.

Solution:

1. Go to the HubSpot portal’s Settings > Integrations > Connected Apps
2. Find the JetStack AI app and disconnect it from within HubSpot
3. Return to JetStack AI and reconnect the portal — this forces a fresh scope approval
4. Approve all requested scopes in the authorization screen

Token and Session Issues

Token Expired

Symptom: Operations that previously worked now fail with “Token expired” or “Invalid refresh token.”

Cause: HubSpot OAuth tokens expire and are refreshed automatically using a refresh token. Token expiration issues occur when:

• The refresh token itself has expired (HubSpot refresh tokens expire after 6 months of non-use)
• A HubSpot admin revoked the app’s access from the portal’s Connected Apps settings
• The app’s client credentials were rotated (JetStack AI update — rare)
• Too many refresh token rotations occurred in a short period

Solution:

1. Navigate to Account > Portals in the JetStack AI dashboard
2. Check the connection status for the affected portal
3. If the status shows “Expired” or “Disconnected,” click “Reconnect”
4. Complete the OAuth flow to obtain a fresh set of tokens
5. Existing imported assets are not affected by a reconnection — only future operations require valid tokens

Reconnection Issues

Symptom: Attempting to reconnect a portal fails or the portal shows a stale connection status.

Cause: Reconnection issues can occur when:

• The previous connection was not fully cleaned up
• A different HubSpot user (without Super Admin access) is signed in during reconnection
• The portal ID changed (extremely rare, but possible during HubSpot account merges)
• The browser has cached OAuth state from a previous connection attempt

Solution:

1. Clear your browser cache and cookies for hubspot.com and jetstack.ai
2. Sign into the correct HubSpot account with Super Admin access
3. In JetStack AI, try removing the portal connection entirely, then adding it fresh
4. If removal fails, contact support to reset the portal connection on the backend
5. Use a private/incognito window to avoid cached state issues

Portal Management Issues

Portal Already Connected

Symptom: When trying to connect a portal, JetStack AI shows “Portal already connected” or “This portal is already linked to your workspace.”

Cause: Each HubSpot portal can only be connected once per JetStack AI workspace. This error appears when:

• The portal was previously connected and the connection still exists (even if expired)
• Another team member in your workspace already connected this portal
• The portal was connected under a different connection type than what you need

Solution:

1. Check Account > Portals to see if the portal is already listed
2. If it is listed with an expired status, reconnect it rather than adding a new connection
3. If it is connected by another team member, coordinate with them — the connection is shared across the workspace
4. If you need a different connection type (e.g., you connected for audits only but now need implementations), update the connection type in the portal settings or reconnect with the desired type

Multi-Portal Management

Symptom: Managing multiple connected portals is confusing, or operations are running against the wrong portal.

Cause: When you have many connected portals, it is easy to select the wrong source or destination portal for operations.

Solution:

1. Use clear, descriptive names for your portal connections (JetStack AI shows the HubSpot portal name and ID)
2. Always verify the portal name and ID before starting an import, deployment, or audit
3. In the deployment wizard, double-check both the source (Asset Library) and destination portal
4. Use the portal filter in the Activity Log to review operations for a specific portal
5. Consider organizing portals by client or project if your workspace has many connections

Wrong Portal Connected

Symptom: You connected a portal but it is the wrong HubSpot account (wrong portal ID or name).

Cause: If you are signed into multiple HubSpot accounts, the OAuth flow may connect the currently active account rather than the intended one.

Solution:

1. Remove the incorrect portal connection from Account > Portals
2. Sign out of all HubSpot accounts in your browser
3. Sign into the correct HubSpot portal you want to connect
4. Return to JetStack AI and add a new portal connection
5. Verify the portal name and ID shown in the OAuth approval screen before approving

Still Stuck?

If none of the above solutions resolve your connection issue:

1. Note the portal ID (visible in the HubSpot URL: app.hubspot.com/[section]/[portal-id]/)
2. Note the exact error message and when it occurs in the flow
3. Try the connection from a different browser or device to rule out local issues
4. Contact support at team@jetstack.ai with the portal ID, error message, and steps you have tried