Overview

The current article is focused on issues specific to the default publishing mechanism. Most of the information is not applicable to Sitecore Publishing Service or Experience Edge Connector.

If you are experiencing issues related to Sitecore Publishing Service or Experience Edge Connector, reach out to Sitecore Support using the Sitecore Support Portal. For more details, refer to How to use the Sitecore Support Portal.

Follow the steps below for troubleshooting the issues related to the default publishing.

Step 1: Check the basics

The first step is to ensure the publishing operation can be started. Only one publishing operation can be running at a time. The publishing mechanism is protected from starting multiple concurrent publishing operations. However, incorrect configuration could lead to violating the one operation rule.

1. Identify the publishing instance.
   There could be only one instance per environment that performs publishing operations. The default Sitecore installation topologies include exactly one instance that could act as the publishing instance – the one with the "Standalone" or "ContentMangement" role.
   The "Publishing.PublishingInstance" setting is empty by default to indicate that the operations should be run on the same instance that was used to initiate the operation. If the environment uses more than one instance that can be used to trigger the publishing operation (for example, multiple instances with the "ContentMangement" role), then the "Publishing.PublishingInstance" setting should specify the name of the publishing instance. In this scenario each instance must have a unique value for the "InstanceName" setting. The "Publishing.PublishingInstance" setting must be set to use one of the instance names. For more details see how to configure multiple Content Management instances.
   In environments that share Sitecore configuration between multiple application instances, for example scaled-out Azure Web App or multiple replicas of a pod in AKS, the "InstanceName" setting should be left empty. This way the instance name is assigned based on "Environment.MachineName" and "HostingEnvironment.SiteName". The publishing instance cannot be scaled out.
2. Ensure the databases are not shared across environments.
   In rare situations the same publishing target database (for example, web) can be used in several environments. Such setup is not supported and may lead to numerous issues including publishing issues.
3. Ensure there are no running or queued publish operations.
   
   • On the publishing instance open the <yoursite>/sitecore/admin/jobs.aspx page to see running and queued jobs.
   • If the "Running jobs" list includes a "Publish" job, then new publishing operations cannot be started.
   • Whenever a publish operation is triggered it will get added to the Jobs Queue and appear in the "Queued jobs" list.
   
   It is normal for jobs to get queued. The jobs get processed one by one once the previous job (with the same name) has been completed. However, if new publish operations are created at a faster rate then the queued jobs are processed, then the delay between triggering the operation and seeing the updated content will keep on increasing.
   There is no mechanism to abort existing jobs. If changes need to be published urgently the application should be restarted to clear the Jobs Queue and abort the current publishing operation and any queued operations. A new publish operation can be started after application restart.
   The long-term solution should be focused on reducing the frequency of the publish operations and/or optimizing the execution time for individual operations. More on this below.

Step 2: Verify Publishing Options

The second step is to ensure the publishing operation is started with the right options to publish the intended changes.

The result of the publishing operation depends on the publishing options. The publishing options are written to the Sitecore Publishing log, for example:

INFO [PublishOptions]: root:null, language:en, targets:Internet, database:web, mode:Incremental, smart:True children:False, related:True

There are 4 publishing modes:

• Three modes are used for publishing the entire content of the database (also known as Publish Site):
  • Incremental (root:null, mode:Incremental, smart:False) – the fastest mode. Only the recently modified items are published.
  • Smart (root:null, mode:Full, smart:Smart) – the balanced mode. Every item is compared to the item in the target database (based on the Revision field). Only the modified items are published.
  • Full (root:null, mode:Full, smart:False) – the slowest mode. Should be used in extreme cases where the content of the publishing target database needs to be repaired.
  For details, see documentation on publishing a site.
• The fourth mode is Single Item (root:{01234567-89AB-CDEF-FEDC-BA9876543210}, mode:SingleItem). Despite its name, it is not guaranteed to publish a single item. The behavior depends on the value of the smart, children, and related parameters:
  • Smart (True|False) – whether to publish the item only if it was modified since the previous publish operation.
  • Children (True|False) – whether to publish the descendants of the item.
  • Related (True|False) – whether to publish items that are related to the item being published.

  For details, see documentation on publishing an item.
  The last parameter should be used with special care. When Related is set to true the number of published items can be very high.
  For details, see how to enable or disable publishing deep scan.

To troubleshoot the process of selecting which items to process during publishing and the process of determining the action that should be performed during publishing (skip|update|create|delete) consider enabling the traceToLog feature, for details see:

https://doc.sitecore.com/xp/en/users/104/sitecore-experience-platform/publish-an-item-to-your-website.html#logging

Important note: all items are publishable by default. To prevent content from being published prematurely, use the Workflow feature, the preview publishing target, and the Publishing Restrictions.

Step 3: The Event Queue

After confirming that the publish operation has started and the scheduled changes have been processed, ensure the changes are reflected on the remote instances.

1. Make sure the Event Queue feature is enabled:

   <setting name="EnableEventQueues" value="true" />

2. Make sure the event queue is being processed.
   Check the last entry in the EventQueue table of the publishing target database (for example, web):

   SELECT MAX(Stamp) FROM EventQueue

   Compare it to the value of the "EQStamp" property in the Properties table of the same database:

   SELECT * FROM Properties WHERE [Key] like '%EQStamp_%'

   Note that multiple properties may match the query. There should be one entry per each active Sitecore instance that uses the database. Outdated entries can be removed. Missing entries require deeper investigation.
   • If the values are equal, then all the entries have already been processed.
   • If the second value is much higher than the first one then the event processing does not work as intended. Remove the affected entries from the Properties table and restart the affected Sitecore instances.
   • If the first value is much higher than the second one then Sitecore instances cannot keep up with the rate of the events.

Event processing can be improved using the following techniques:

1. The Cache Key Indexing feature. The feature introduces additional cache index that speeds up the process of removing outdated cache entries by a partial cache key.
2. The "EventQueue.SavedItemRemote.SerializeAllFields" setting. Changing the value of the setting to false can significantly reduce the amount of information transmitted via the EventQueue. The change should be applied carefully when using custom “item:saved:remote” event handlers that rely on the changes to specific item fields.

The timingLevel feature can be used to identify event handlers that slow down event processing, for example:

<events timingLevel="high">

When the feature is enabled the application measures and logs processing time for each event including execution time for individual event handlers. The feature should be used for diagnostics purposes only.

Step 4: Caching

By this step the changes should be reflected on the remote instances.

If the changes are not reflected the issue is likely caused by one of the caching layers. The fastest way to test the theory (and to mitigate the issue) is to clear all caches, for example, by restarting the application.

If the restart helps, then the issue is caused by application caches, i.e. the cached result is stored somewhere in the application memory. To troubleshoot the issue, capture a memory dump of the process that serves cached results.

Use the Windows debugger (WinDbg) with the SOSEX debugging extension to locate the cached value, for example:

!strings /m:"*cached text*"

For each matching entry find what keeps it in memory, for example:

!mroot <address_of_the_string>

If the restart does not help then the changes are likely cached on the client side, for example, CDN cache or browser cache.

If clearing the application caches does not help check the contents of the database directly to ensure the changes were published. This scenario is unlikely as any publishing issues should have been caught when checking Sitecore log files in step 2.

Step 5: Contacting Sitecore Support

If the suggested steps do not help to resolve the issue, reach out to Sitecore Support and share the necessary details for in-depth investigation. Refer to KB1003443 for more details on how to collect diagnostics information on publishing issues.