Review and troubleshoot customer agent content source sync errors

When syncing content sources with the customer agent, you may encounter errors. Below, learn how to review the sync status of content sources and troubleshoot common errors to ensure your customer agent is using the most up-to-date content. 

Review the sync status of content sources added to the customer agent 

Before troubleshooting a specific error, check the sync status of all your added content sources:

1. In your HubSpot account, navigate to Service > Customer Agent.
2. Navigate to the Manage tab.
3. In the left sidebar menu, click Content sources.
4. In the top right of the table, click the Failed tab. 
5. In the table, review the specific content sources that failed to sync and the error message associated with them.

Understand and troubleshoot content source errors

The knowledge source no longer exists or can't be reached

What the error means

The content could not be retrieved. This happens if the URL returned a 404 Not Found error, the domain name couldn't be located, or the content was deleted.

How to resolve the error

• Confirm that the URL is correct and the page is publicly accessible.

• Check the website's security settings, such as a firewall, that might block the crawler.

• If needed, work with a developer on your team to allow list the IP range 54.174.58.224/27 on the page.

Website content couldn't be loaded 

What the error means

The crawler was unable to load or render the page. This is typically caused by complex JavaScript on the page.

How to resolve the error

• Simplify the code on the page .
• Copy and paste the content into a simpler webpage or upload it as a document (PDF, DOCX).

The website returned an unexpected response

What the error means

The site responded in a way that the crawler couldn't understand. For example, there were too many redirects or unsupported status codes. 

How to resolve the error

• Ask your site admin or developer to check for redirect loops or unusual status codes.

• If needed, correct any redirect configuration and attempt to add the content again. 

Crawling is blocked by the site's robots.txt file

What the error means

The site's robots.txt file contains rules that do not allow our crawler to access the page. The HubSpot crawler follows the this standard protocol. 

How to resolve the error

The page is blocked from being read by automated tools

What the error means

A "noindex" meta tag in the head HTML of your pages is preventing them from being indexed or crawled. 

How to resolve the error

Remove the "noindex" meta tag from the page. 

The page couldn't be loaded because it's private or blocked

What the error means

The crawler got a 401, 403, or similar error. The page is likely protected, requires a login, or is blocked by a firewall. 

How to resolve the error

• Make the page publicly accessible.

• If the content is private, upload it as a PDF/DOCX instead.

• Work with your site admin or a developer on your team to ensure that the IP range 54.174.58.224/27 is not being blocked or filtered on the page you attempted to add. 

This content couldn’t be synced because its URL is missing

What the error means

HubSpot pages (website and landing pages, blog posts etc.) need a valid URL so the system can load them. The linked URL is either blank or invalid. 

How to resolve the error

Follow the steps in this article to update the URL of the HubSpot content. Then, attempt to add the content again.

The website had a server issue, possibly due to downtime or a security policy

What the error means 

The server responded with a general failure error (500 or 503). This typically indicates temporary site downtime, or that the server is actively blocking the HubSpot crawler.

How to resolve the error 

• Visit the URL to make sure the page loads properly. 
• If the page loads correctly, the site may be blocking the HubSpot crawler. Work with your site admin or a developer on your team to ensure that the IP range 54.174.58.224/27 is not being blocked.

The HubSpot content is not published, so it can't be synced 

What the error means

The HubSpot hosted content you tried to add is currently in draft status and has not yet been published.

How to resolve the error

Publish the page, then attempt to add the content again. If you don't want to make the content publicly accessible, learn more about how to make content private. 

This file type isn’t supported, so the content wasn’t synced

What the error means

The file you tried to add is not in a supported format. The customer agent supports the following file types:
.docx, .htm, .xhtml, .cfg, .pptx, .mpg, .conf, .mpeg, .csv, .json, .html, .text, .txt, .mp4, .pdf, .rst, .avi, .mov, .xml, .md, and .webm.

How to resolve the error 

Convert the file into one of the supported formats listed above, then attempt to add the content again. 

The document exceeds size limits, so it wasn't processed

What the error means

The file is too large. The customer agent supports:

• HTML/XHTML files: up to 25 MB
• All other files: up to 500 MB

How to resolve the error

Try splitting the file into two or more smaller files, then attempt to add the content again. 

A secure connection couldn’t be made, so the page couldn’t be crawled

What the error means

An error occurred while attempting to establish a secure HTTPS connection. The server certificate may be expired or invalid, or the server uses an outdated TLS configuration. 

How to resolve

• Visit the URL to make sure the page loads properly.
• If the browser shows a certificate error, work with your site admin or developer to update or properly configure the website's SSL/TLS security certificate and settings.