| 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. |
