Troubleshooting Extension Issues

This page covers the most common issues you may encounter with the JetStack AI Chrome Extension, organized by symptom. Each entry includes the likely cause and a concrete solution.

---

Extension Does Not Appear in Sidebar

Symptom: You click the JetStack AI icon in the Chrome toolbar but no sidebar opens, or the side panel is empty.

Cause: The extension may not be installed correctly, may be disabled, or Chrome’s side panel feature may not be available.

Solution:

• Navigate to chrome://extensions and confirm JetStack AI is listed and enabled (toggle is blue).
• Verify your Chrome version is 116 or later. Earlier versions do not support the sidePanel API.
• Try clicking the JetStack AI icon again. If the side panel area opens but is blank, right-click the panel and select “Reload” or close and reopen the panel.
• If the extension is missing entirely, reinstall it from the Chrome Web Store.

---

”Not on HubSpot” Message

Symptom: The sidebar opens but displays a message saying it only works on HubSpot pages.

Cause: The extension checks the active tab’s URL to determine if you are on a HubSpot application page. If the URL does not match a known HubSpot domain, the extension shows this message.

Solution:

• Confirm your URL starts with one of the recognized HubSpot application domains: app.hubspot.com, app-na1.hubspot.com, app-eu1.hubspot.com, or another regional hublet.
• The extension does not activate on www.hubspot.com, knowledge.hubspot.com, developers.hubspot.com, or other HubSpot marketing/docs sites. You must be on the application itself.
• If you are on a valid HubSpot application page and still see this message, try refreshing the HubSpot tab and reopening the sidebar.

---

Authentication Failure on Sign-In

Symptom: You enter your credentials but sign-in fails with an error, or the sidebar returns to the sign-in screen after a brief loading state.

Cause: Incorrect credentials, network issues, or a problem with the Clerk authentication service.

Solution:

• Double-check your email and password. These are the same credentials you use for the JetStack AI web dashboard.
• Try signing in to the web dashboard directly. If that also fails, your credentials may be incorrect or your account may be locked.
• Check your network connection. The extension needs to reach Clerk’s authentication servers and the JetStack AI backend.
• If you use SSO, ensure your identity provider session is active. Try the SSO flow again.
• Clear the extension’s stored data: go to chrome://extensions, find JetStack AI, click “Details,” then “Clear data.” Sign in again.

---

Token Refresh Failures

Symptom: The extension works initially but after some time you get authentication errors, API calls fail, or you are unexpectedly signed out.

Cause: The JWT token issued at sign-in has a limited lifespan. The extension automatically refreshes it with a 20-second TTL buffer before expiry. If the refresh fails (network interruption, Clerk service issue), subsequent API calls fail.

Solution:

• Close and reopen the sidebar. This triggers a fresh token check and refresh.
• If that does not resolve it, sign out and sign back in from the sidebar.
• If token refresh failures are frequent, check whether a VPN, proxy, or browser extension (ad blocker, privacy tool) is blocking requests to Clerk’s domains.

---

Hublet Routing Errors

Symptom: API calls fail intermittently, or you see errors mentioning a 488 status code in the browser console.

Cause: HubSpot uses regional routing. If the extension sends a request to the default api.hubspot.com but your portal is hosted on a different hublet (e.g., api-na1.hubspot.com), HubSpot returns a 488 status code indicating the wrong region.

Solution:

• In most cases, the extension handles this automatically — the service worker detects the 488 response, extracts the correct hublet URL, and retries the request. No action is needed from you.
• If 488 errors persist and cause visible failures, try refreshing the HubSpot tab to ensure the extension picks up the correct hublet from the page context.
• Check the browser’s developer tools console (chrome://extensions > JetStack AI > “Inspect views: service worker”) for repeated 488 entries. If the correct hublet cannot be determined, contact JetStack AI support with the console output.

---

CSRF Token Issues

Symptom: Import or audit operations fail with authentication-related errors even though you are signed in to both JetStack AI and HubSpot.

Cause: The extension’s service worker reads HubSpot’s CSRF cookies from the browser to authenticate internal API calls. If these cookies are missing, expired, or blocked, internal API calls fail.

Solution:

• Confirm you are logged in to HubSpot in the active tab. Navigate to any HubSpot application page and verify you are not on the login screen.
• If you recently cleared your browser cookies, log in to HubSpot again. The CSRF cookie is set during the HubSpot login flow.
• Check that no browser extension (privacy tools, cookie managers) is blocking or auto-deleting HubSpot cookies.
• Try opening HubSpot in a fresh tab, waiting for the page to fully load, then reopening the JetStack AI sidebar.

---

Slow Performance or Unresponsive Sidebar

Symptom: The sidebar takes a long time to load, interactions are laggy, or the UI freezes temporarily.

Cause: Large data sets (many assets, extensive task history), multiple simultaneous Firestore listeners, or Chrome resource constraints.

Solution:

• Close other Chrome side panels or extensions that may be competing for resources.
• If the Assets tab is slow, use search and type filters to narrow the data set rather than scrolling through all assets.
• Check Chrome’s Task Manager (Shift + Esc) to see if the JetStack AI service worker or sidebar panel is consuming excessive memory. If so, close and reopen the sidebar.
• Ensure your Chrome installation is up to date. Performance improvements ship with browser updates.

---

Extension Crashes or White Screen

Symptom: The sidebar goes completely white, shows a crash error, or stops responding entirely.

Cause: A JavaScript error in the sidebar UI, a service worker crash, or a Chrome update that changed API behavior.

Solution:

• Close the side panel and reopen it. This reinitializes the UI iframe.
• If that does not work, go to chrome://extensions, disable JetStack AI, then re-enable it.
• Check for extension updates: enable Developer mode at chrome://extensions and click “Update.”
• As a last resort, uninstall and reinstall the extension. Your data is stored on the server, so nothing is lost.
• If crashes are reproducible, report the issue to JetStack AI support with steps to reproduce and your Chrome version number.

---

Audit Capture Stops Mid-Way

Symptom: An audit’s progress bar stops advancing and the current block stays in “capturing” state indefinitely.

Cause: The HubSpot session expired during capture, the tab was closed, or a network interruption broke the connection.

Solution:

• Confirm the HubSpot tab is still open and you are still logged in.
• Check your network connection.
• If the session expired, log back in to HubSpot and start a new audit. Partially captured audits cannot be resumed.
• For large portals, ensure your machine does not go to sleep during the audit (adjust your power settings if needed).

---

Clearing Extension Cache and Data

If none of the above solutions resolve your issue, a full reset of the extension’s local state can help:

1. Go to chrome://extensions
2. Find JetStack AI and click Details
3. Click Clear data (this removes stored tokens and preferences)
4. Close all HubSpot tabs
5. Reopen a HubSpot tab, open the JetStack AI sidebar, and sign in again

This does not affect your server-side data — all assets, tasks, audit results, and workspace settings remain intact.

What’s Next

• Installing the Extension — Reinstall if needed
• Extension Overview — Review the sidebar layout and navigation