Common Push Publishing Failures
When push publishing an object or bundle fails, it is often because of one of the following common problems:
- The push publish connection was poorly established.
- Temporary or intermittent network errors may prevent a push publish from succeeding.
- 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.
- New content should never be created directly on the receiving server.
- Both the sending server and receiving server are using the same license.
- Each dotCMS server must have its own unique license.
- 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:
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.
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.
Dependencies
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.
Restoring Data From the Receiving Server
Occasionally, a user may accidentally delete a piece of content, a Content Type, etc., from the sending server. If this data still exists on the receiving server, it is possible to bring the two back into synchronization.
Access the receiving server, select any necessary content and add it to a bundle. Then, from the Bundles tab under Site → Publishing Queue, select that bundle and select Generate / Download from the “hamburger” (three dots) button at the right.
At this time, it will prompt you for a push publishing filter. Care should be taken in this selection, to ensure extraneous data is not accidentally included by dependency. The Only Selected Items filter may suffice in many cases, though the safest practice is to create a custom filter that explicitly excludes any content types and objects for which the upstream environment is the source of truth. Ultimately, clearly defined sources of truth — i.e., where each sort of content should be authored — is a key consideration of push publishing architecture.
For example, if the goal is to transfer data from a production server to a development server — a common case to ensure developers can test using real data — then we recommend creating a custom filter that explicitly excludes code files, templates, and containers.
Once you have downloaded the bundle, browse to the same Bundles tab in the Publishing Queue of the sending server, and use the UPLOAD BUNDLE button to add it.
