Common scenarios
| Symptom | Likely cause | Fix |
|---|---|---|
| Sync fails at connect with portal ID error | The access token is invalid, expired, or from a different HubSpot account | Create a fresh Private App access token for the correct portal and update the source. |
| Sync completes but zero articles | All Knowledge Base articles are still drafts (unpublished) | Publish articles in HubSpot. Site Search only indexes published content. |
| Some published articles are missing | Site Search is query-based; an article’s title/body may not match any of the broad search seeds OpenCX uses | Publish the article, confirm it appears in your public help center search, or use the Website crawler against your help domain for full coverage. |
| Draft articles never appear | Working as designed — drafts are not exposed via HubSpot’s third-party APIs | Publish in HubSpot, or ingest draft content via file upload / website crawler. |
| Article body looks like a short snippet, not full HTML | Site Search returns indexed snippets, not the full article HTML | Expected for this source. Use the Website crawler if you need full-page HTML. |
| Sync is slow / times out on a large knowledge base | full_refresh_overwrite re-queries the search index across multiple broad search terms each run | Reduce the connection’s sync cadence on the Airbyte schedule. |
| None of the above | — | Contact support with the connection ID and a sample article URL. |
Related Documentation
Connect HubSpot Knowledge Base
Re-check the token and limits.
HubSpot Knowledge Base overview
What this source does.
Website crawler
Fallback for full HTML or scoped subsets.
Connect a knowledge source
All sources.