> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot Knowledge Base troubleshooting

> Start at the HubSpot Knowledge Base source row in Data Sources. Recent sync errors show there; for "sync completed but articles are missing", open AI Instructions and filter by HubSpot Knowledge Base.

Start at the **HubSpot Knowledge Base** source row in [**Data Sources**](https://platform.open.cx/data-sources). Recent sync errors show there; for "sync completed but articles are missing", open AI Instructions and filter by **HubSpot Knowledge Base**.

## 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 fails with a GraphQL or auth error**            | The token is missing `cms.knowledge_base.articles.read`, the private app was not reinstalled after adding the scope, or the account does not expose Knowledge Base GraphQL | Add the scope, reinstall/save the private app, confirm `KB` appears in HubSpot GraphiQL for the portal, then update the source.                           |
| **Sync completes but zero articles**                   | All Knowledge Base articles are still **drafts** or unpublished                                                                                                            | Publish articles in HubSpot, then run the sync again.                                                                                                     |
| **Some published articles are missing**                | The articles are not returned by HubSpot Knowledge Base GraphQL for this portal or they are not in the latest Knowledge Base toolset                                       | Confirm the articles appear in HubSpot GraphiQL under `KB.knowledge_article_collection`, or contact HubSpot support to enable KB GraphQL for the account. |
| **Draft articles never appear**                        | Working as designed — this source only imports published articles                                                                                                          | Publish in HubSpot, or ingest draft content via file upload / website crawler.                                                                            |
| **Article body is empty**                              | HubSpot returned an empty `hs_body` for that article                                                                                                                       | Check the article in HubSpot GraphiQL. If `hs_body` is empty there too, update the article content in HubSpot.                                            |
| **Sync is slow / times out on a large knowledge base** | `full_refresh_overwrite` re-queries the full Knowledge Base GraphQL collection 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

<CardGroup cols={2}>
  <Card title="Connect HubSpot Knowledge Base" icon="plug" href="/knowledge/sources/hubspot-kb/connect">
    Re-check the token and limits.
  </Card>

  <Card title="HubSpot Knowledge Base overview" icon="hubspot" href="/knowledge/sources/hubspot-kb/overview">
    What this source does.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for full HTML or scoped subsets.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>