Troubleshooting Smart search on Azure

This page provides guidance for troubleshooting issues related to the Smart search feature when running Kentico application on Azure. Please note that each section applies either to Web Apps, Cloud Services or both, as specified.

Smart search indexes are not being rebuilt or there are hanging tasks in the system

If the Smart search indexes are not being built correctly or if many Smart search tasks are stuck in the system, there is probably a conflict between the Smart search files located in the file system of the application and files located on the blob storage. When an application is mapped to the blob storage, files in the file system cannot be modified. Therefore, the system is not able to delete the old search indexes.

Please proceed to the section which corresponds to your Azure environment.

Cloud Services - removing Smart search files


Quick fix

The solution for this issue on Cloud Services is to delete all files in the ~/App_Data/CMSModules/SmartSearch folder. Connect to your service through remote desktop and delete the files remotely in the file system.


Delete the files in the ~/App_Data/CMSModules/SmartSearch folder and redeploy the cloud service. Also delete the files every time before you deploy your application to Cloud Services.

Web Apps - removing Smart search files

Applies to: WEB APPS

Quick fix

Immediate solution for this issue on Web Apps is to delete all files in the ~/App_Data/CMSModules/SmartSearch folder. You can connect to your Web Apps service through FTP and delete the files in the file system.


However, we recommend a different approach. Azure Web Apps do not require to be connected to the blob storage - connecting a blob storage is optional. Therefore, to avoid several problems together, we recommend that you map only the media library folders to the blob storage and leave all other files in the file system of the application.

To map only the media library folder to the blob storage, see Configuring Kentico to store only media files on Azure storage.

However, if you want to connect the blob storage using the CMSExternalStorageName web.config key, which maps the whole file system of the application to the blob storage:

  • You need to delete all Smart search files in the application file system (as described in this section).

Deleting .lock files


Quick fix

If Smart search functionality is not working properly, you might try deleting files with the .lock extension on the blob storage. Connect to your blob storage (for example through Cloudberry for Azure) and manually delete them.


A blob storage is shared between all instances of Kentico. If your Azure environment (Cloud Services or Web Apps) operates in multiple instances, it is important to prevent collisions. Therefore, to prevent multiple instances from manipulating the same index at the same time, Kentico uses the concept of locking the index for exclusive write. Every time the Smart search needs to manipulate some search index, it creates a special file with the .lock extension. This file indicates that some search indexer is working with the index. When the work is done, the system deletes the file from the storage.

There are two different lock files in the blob storage:

  • searchtaskindexer.lock – located in ~/App_Data/CMSModules/SmartSearch directory.
  • write.lock – located in the directory of some particular search index.

In some occasions, these lock files may not get deleted. This may happen when the process that works on the search index ends unexpectedly. When this happens, Smart search is going to be stuck. The solution is to manually delete the lock files.


On Azure Web Apps, this problem might occur again if you store the search indexes on the blob storage. We recommend that you either:

SmartSearchWorker role troubleshooting on Cloud Services


The SmartSearchWorker role is part of the Kentico Azure project designed to be used on Azure Cloud Services. If you are not running the Cloud Services or not using the SmartSearchWorker role, this section does not apply to your environment.

When you are convinced that every setting and every configuration is correct and the worker role is running correctly, but still not processing the search tasks, you can look for an error in the Event log.

If you do not find anything related in the event log, try the following troubleshooting practice:

  1. Enable remote desktop for the worker role.
  2. Connect to the worker role through the remote desktop access.
    1. Switch to the Roles and Instances tab.
    2. Select the worker role instance.
    3. Click Connect.
  3. Look into the Smart search log in App_Data/CMSModules/SmartSearch/workerlog.txt.
  4. Look into the Windows event log using Event viewer. Try looking for errors from around the time the worker role was starting.

Next steps can differ based on the error you find. But the error should provide you with enough information to start with.