Troubleshooting Push Publishing

Last Updated: Aug 9, 2021
documentation for the dotCMS Content Management System

Common Push Publishing Failures

When push publishing an object or bundle fails, it is often because of one of the following common problems:

  1. The push publish connection was poorly established.
    • Temporary or intermittent network errors may prevent a push publish from succeeding.
  2. The object was created separately on both the authoring server AND the receiving server.
    • New content should never be created directly on the receiving server.
      • Content on the receiving server should be created only by pushing it from the authoring server.
  3. Both the sending server and receiving server are using the same license.
    • Each dotCMS server must have its own unique license.
  4. A bundle is being uploaded to the same server it was created on.
    • To prevent overwriting objects with old versions of the same objects, dotCMS will only allow you to upload a bundle to a server other than the one where the bundle was created.

The dotCMS troubleshooting tools listed below can help track the source of push publishing errors in the system.

Bundle Detail

After a push has failed, you may view more information about the bundle and the reason for the failure in the Publishing Queue screen (Site -> Publishing Queue).

Select the **Status/History tab, and double-click any bundle to reveal the bundle detail, including a message for the attempt to push publish the bundle. For example, the error message in the image below indicates that the push publishing connection was not properly configured and the receiving server could not be reached:

Bundle Detail

The dotCMS Log

The dotCMS log file is accessible from Log Files tab in the System -> Maintenance screen. Select dotcms.log in the Tail select box. The push publishing error messaging displayed in the log is often similar to the error message shown in the bundle detail, but the log file can sometimes provide additional context, such as error messages before the push publish failed.

Log Files

Integrity Checker {#IntegrityChecker} - Dynamic Push Publishing Endpoints only

To view the Integrity Checker, select the Publishing Environments tab in the System -> Configuration screen, and press the Check Integrity button for your publishing environment. The Integrity Checker checks for duplicate objects and content which has been created separately on both the sending and receiving server, which might cause conflicts.

For more information, please see the Integrity Checker documentation.

Integrity Checker


It's also important to note that if you attempt to push an object or bundle, the specific object or objects in the bundle may not be the source of the push publishing error. When you push any target object, dotCMS automatically identifies whether any additional objects need to be pushed for the target object to display properly on the receiving server (such as Content Types, related content, etc.); so if a push publish fails, it may be due to a conflict with an object which is not included in your bundle, but which an object in your bundle depends on.

Static Publishing Endpoints: Since the static push publishing bundler creates static HTML representations of pages, it is especially important, that when using this type of endpoint, that ALL related/linked/associated files and objects be pushed together. For this reason, it is best practice to push *entire sites to static endpoints, instead of single objects such as folders or pages.

For more information on how objects are push published and what objects are included in each bundle, please see the Push Publishing Dependencies documentation.

On this page