Audit Troubleshooting

This page covers the most common issues you may encounter when running audits, generating insights, or sharing reports, along with their solutions.

Audit Stuck in Processing

Symptom: The audit has been in a processing state for an extended period without progressing.

Common causes and solutions:

• Large portal size — Portals with thousands of assets take longer to scan. Audits on very large portals may take 10-15 minutes. Wait for at least 15 minutes before considering the audit stuck.
• HubSpot API rate limits — If your portal is near its API rate limit (due to other integrations or activity), audit requests may be queued. Wait for the rate limit window to reset (typically 10 seconds for standard limits).
• Network interruption — A temporary network issue between JetStack AI and HubSpot can stall progress. The audit will typically resume automatically. If it does not resume after 15 minutes, cancel and re-run.

If the audit remains stuck after 20 minutes:

1. Cancel the audit from the audit detail view.
2. Wait 5 minutes.
3. Launch a new audit on the same portal.

Audit Failed

Symptom: The audit status shows “Failed” with an error message.

Common Failure Reasons

Error	Cause	Solution
OAuth token expired	The portal’s OAuth connection has expired	Reconnect the portal in Client Accounts. See Reconnecting a Portal.
Insufficient permissions	The connected HubSpot user lacks required scopes	Reconnect with a Super Admin account to ensure all scopes are granted.
Portal not found	The HubSpot portal ID is invalid or the portal has been deleted	Verify the portal exists in HubSpot and reconnect.
Timeout	The audit exceeded the maximum processing time	Re-run the audit. If it times out repeatedly, try a template with fewer blocks.
Internal error	An unexpected server-side issue	Wait a few minutes and retry. If it persists, contact support.

Extension Capture Interrupted

Symptom: When running an audit via the Chrome Extension, the capture process stops mid-way.

Solutions:

• Keep the HubSpot tab active — The extension requires the tab to remain open and active during capture. Switching to another tab or minimizing the browser can interrupt the process.
• Disable browser sleep — Some browsers suspend inactive tabs. Ensure your browser settings allow the HubSpot tab to remain active.
• Check extension version — Ensure you are running the latest version of the JetStack AI Chrome Extension. Update from the Chrome Web Store if needed.
• Retry the capture — Close and reopen the extension sidebar, then start the capture again.

Tier Mismatch

Symptom: Certain blocks or features are unavailable, or you see a “requires upgrade” message.

Cause: Your plan does not include the features required by the selected template or blocks.

Solutions:

• Check your plan — Navigate to Settings > Billing to verify your current plan.
• Use a compatible template — Switch to a template that only includes blocks available on your plan.
• Upgrade your plan — If you need premium blocks or features, upgrade to a higher tier.
• Remove premium blocks — If using a custom template, edit it to remove blocks that require a higher plan.

Rate Limit Errors

Symptom: The audit reports rate limit errors or progresses very slowly.

Cause: HubSpot enforces API rate limits. If your portal has many active integrations making API calls, the available rate limit budget may be low.

Solutions:

• Reduce concurrent API usage — Temporarily pause other integrations or tools that make heavy API calls to the same portal.
• Run audits during off-peak hours — Schedule audits for times when other integrations are less active.
• Use a simpler template — Templates with fewer blocks make fewer API calls.
• Wait and retry — HubSpot rate limits reset on a rolling window. Waiting a few minutes and retrying often resolves the issue.

Block Execution Failure

Symptom: Individual blocks within an audit show a “failed” status while the rest of the audit completes successfully.

Cause: A specific block encountered an error during data collection or scoring. This can happen if:

• The HubSpot API returned an unexpected response for that block’s data
• A required HubSpot feature is not enabled on the portal (e.g., querying Service Hub data on a portal without Service Hub)
• A temporary API error affected just that block’s requests

Solutions:

• Check hub availability — Ensure the portal has the HubSpot hub required by the failed block.
• Re-run the audit — Temporary errors often resolve on the next run.
• Skip the block — If the block is not essential, skip it in the report settings.

Missing Data Points

Symptom: A block shows a score, but some data points within it show “N/A” or “No data.”

Cause: The data point requires information that does not exist in the portal. For example, a data point measuring “percentage of workflows with goal criteria” will show no data if there are zero workflows.

This is expected behavior. Data points that cannot be measured are excluded from scoring calculations, so they do not unfairly penalize the portal.

If you believe data should exist but is not being captured:

• Verify the feature is configured in HubSpot
• Check that the OAuth connection has the required scopes
• Reconnect the portal and re-run the audit

Report Not Generating

Symptom: Clicking “View Report” shows a loading state or error.

Solutions:

• Wait for audit completion — Reports are only available after the audit finishes processing. Check the audit status.
• Check branding configuration — Invalid logo URLs can cause report rendering issues. Verify that all logo URLs point to accessible images.
• Try a different browser — Report rendering issues can occasionally be browser-specific. Test in Chrome, Firefox, or Safari.
• Clear browser cache — Cached assets from a previous version can cause rendering issues.

AI Insights Failure

Symptom: AI insights show a “failed” status instead of generated content.

Common causes:

• AI service temporarily unavailable — The AI model may experience brief outages. Wait a few minutes and click Retry on the failed insight.
• Insufficient data — If a block has very few data points or all data points returned N/A, the AI may not have enough context to generate a meaningful insight.
• Timeout — Large blocks with many data points may take longer to process. Retry the generation.

Solutions:

1. Click Retry on the failed insight. Most failures are transient.
2. If retry fails, wait 5 minutes and try again.
3. If the issue persists across multiple blocks, contact support.

Individual block insights can be retried independently. A failure in one block does not affect other blocks’ insights.

Report Sharing Issues

Symptom: Clients report they cannot access the shared report.

Troubleshooting checklist:

Issue	Check	Solution
”Invalid password”	Client is entering the wrong password	Resend the current password. Copy it from the audit settings panel.
Page not loading	URL may be wrong or incomplete	Resend the full URL. Copy it using the Copy Link button.
Blank report	No insights are published	Publish the insights you want clients to see. See Publishing.
Custom domain not working	DNS propagation delay	Wait 30 minutes after activation. Use the standard URL as a fallback.
Old password not working	Password was recently changed	Send the updated password to the client.
Report content looks wrong	Browser caching	Ask the client to hard-refresh the page (Ctrl+Shift+R or Cmd+Shift+R).

Getting Help

If none of the above solutions resolve your issue:

1. Note the audit ID (visible in the audit detail view URL).
2. Note the portal Hub ID of the affected portal.
3. Take a screenshot of any error messages.
4. Contact JetStack AI support with these details for faster resolution.