Causes for ContactLockException error

  • Description

    The ContactLockException error is an exception that can occur in the process of locking a Sitecore XP contact.

    In Sitecore XP, a web-cluster or an out of request worker can lock a contact. Only the owner of the lock can modify contact data. Locks were introduced to avoid data corruption when there are multiple threads trying to modify the same contact's data at the same time.

    Note: In Sitecore XP 9.0 and later versions, contacts are no longer locked, and the ContactLockException error therefore does not occur.

    Locks have a timeout setting. When a web-cluster locks a contact, the web-cluster has to extend the lock from time to time to keep the contact locked while the contact is active on a website. The lock remains until the contact data is saved to the database at the end of the contact's sessions with the website.

    There are several scenarios that can result in a ContactLockException error:

    • The external session is initialized (see the initializeExternalSession pipeline) and the contact lock cannot be obtained because the contact is already locked. The external session is typically initialized when the Sitecore.Analytics.Tracking.External.InteractionRegistry class is used for importing offline interactions into a system.
    • The Tracker.Current.Session.Identify method is called to identify the contact and the existing contact found by the identifier cannot be locked because an out of request worker already holds the lock. If the contact is already locked by a web-cluster, the session is redirected to that web-cluster, and an exception is not thrown.
    • The Sitecore.Analytics.Tracking.ContactManager.TryLoadContact method is called to load the contact by ID, and the loaded contact is already locked by a web-cluster, but the web-cluster name is empty. The TryLoadContact method is typically called when a request is made to a page and tracking is enabled.
    • An attempt to extend the contact lease is not successful. As mentioned previously, the lock has an expiration time, so it is necessary to periodically check if the lock is about to expire. If it is about to expire, then it is necessary to extend the lock in xDB. Such a periodic check is implemented in the endAnalytics pipeline, which is called at the end of every HTTP request when tracking is enabled.
    • An attempt is made to remove PII sensitive data from the contact and the contact lock cannot be obtained because the contact is already locked. This is only applicable for Sitecore XP 8.2 Update-7 and later.
  • We recommend two ways to avoid these exceptions:

    • Retry the failed operation, for example, a call to the Tracker.Current.Session.Identify method. The call can fail at first because the contact is locked, but a new attempt might succeed if the lock has been released in the meantime.
    • Reduce the lock timeout time for out of process workers in order to minimize the time a contact remains locked by a worker.

Applies to:

CMS 7.5 Initial Release - 8.2 Update-7

CMS 9.0 Initial Release

October 10, 2018
October 10, 2018

Reference number:

198208, 124871