1. Documentation /
  2. WooCommerce Product Search /
  3. FAQ


The WooCommerce Product Search search engine and its tools are developed following the highest standards in Software Engineering. It is duly designed, developed and tested to work on a broad variety of setups, powering thousands of shops with huge amounts of products – Even so, given the vast variety of tools that can compose a particular deployment, things can go wrong. This section provides some pointers to what you can do to figure out what’s wrong, how to fix it and provide a powerful search experience for your customers.

Searching doesn’t find any products or only some

↑ Back to top

If the index is not fully completed, the search engine will only provide results from those products that have already been processed.

Check under WooCommerce > Settings > Search > Index whether the index has reached 100%. Also check the next question for possible reasons.

From time to time, an updated version of the extension will require an update to the database. In that case, you will see this notice:

Once you click the Update button, the search engine will start to re-index the site’s products. If your site has a large set of products and/or variations, this may take some time. For example, it can take up to a couple of hours to re-index a site with 10.000 products – this of course depends very much on the performance of your site’s server and its available resources. To minimize the impact on the browsing experience for your customers, we recommend to initiate such updates during low traffic hours.

The indexer never completes processing all products, why could that be?

↑ Back to top

Scheduled tasks (cron) are not working correctly.

↑ Back to top

If you get indications under WooCommerce > Settings > Search > Index that scheduled tasks (cron) seem to be failing, there can be several reasons for this to happen. You have the option to run the indexer manually in that case by clicking the Run button, or try to apply one of the solutions suggested below. Normally, the indexer only needs to process existing products initially so that they are included in searches  – after you have installed and activated the extension, any new products or modified products will be indexed instantly.

Please note that the indicator WordPress cron found under WooCommerce > Status > WordPress environment does not guarantee that scheduled tasks are working correctly, as it merely reflects whether the constant DISABLE_WP_CRON is used or not.

Your site has little or no traffic.

↑ Back to top

On low traffic sites, staging sites or sites that are running on localhost (your own computer), scheduled tasks (cron) are only triggered sporadically and in some cases not at all. Consider enabling scheduled tasks at the system level – see Hooking WP-Cron Into the System Task Scheduler on how to achieve this.

If you are using Docker, this article has indications on how to trigger WordPress cron every minute.

Or simply trigger the indexer manually by clicking the Run button.

Password-protected sites.

↑ Back to top

Access to your site is protected by password on the server level and scheduled tasks (cron) fail to execute due to lack of permission when the server receives the wp-cron request. Remove the password protection during tests or trigger cron events manually using the Run button.

The PHP memory limit is exhausted.

↑ Back to top

Increase the PHP memory limit as indicated in the article Increasing the WordPress Memory Limit.

There are issues during processing.

↑ Back to top

Errors in third-party plugins, themes or customizations cause issues during processing and thus the indexer cannot successfully process the entries. Disable plugins that are up-to-date but create issues. Update plugins that have not been updated in a while. Fix errors in customizations. Switch to a theme that is error-free. Plugins, themes and customizations should not produce any entries in the debug log. If they do, consider alternatives or fixing them.

Please check the next question on how to enable debugging and review the debug log entries produced for errors.

Variable products take longer to index

↑ Back to top

When you have variable products with many variations, the indexer will need additional time to index each variation. This is correct as it will take all characteristics of each product variation into account.

The time required to process the variable product and all its variations is proportional to the number of variations of the product. Although the engine will try to avoid errors related to excessive usage of resources, on some setups with low limits and depending on the overall resource consumption of your server, you may see a “PHP Fatal error: Maximum execution time of … seconds exceeded”. Even if this occurs, the indexer will eventually index all variations in due time during successive indexing runs. To avoid such errors at all, you can also increase the PHP max_execution_time.

How can I enable extension-specific debugging?

↑ Back to top

In your site’s wp-config.php (this file is located in the root folder of your site) enable WordPress debugging and specific debugging for the extension by adding these lines:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WPS_DEBUG', true );

This will log any PHP notices, warnings and errors to the log file along with information about activities and events related to the search engine. The log file typically resides in wp-content/debug.log.

For additional debugging options, please refer to this extension’s Debugging section of the API documentation.

Issues caused by Plugin and Theme Conflicts

↑ Back to top

How to test for Plugin and Theme Conflicts

↑ Back to top

Issues are often caused by incompatible themes, conflicting plugins, incompatible customizations or even syntax errors in source files (the latter are most often found in badly coded templates or customizations).

To find out what exactly is causing issues that stop the search engine and its features from working, please read the section How to Test for Plugin and Theme Conflicts where steps to discover the causes of conflicts are detailed.

Avoid generic Optimization Plugins

↑ Back to top

Experience has shown that generic optimization plugins rather break sites instead of optimizing them.

Such plugins interfere with appropriate functionality and can cause a variety of issues. They can cause failure to load needed resources or even go as far as to modify or delete essential parts of the database.

We recommend to avoid using the following and similar plugins, as they can cause loss of functionality and loss of data:

  • Avoid: Autoptimize
  • Avoid: Plugin Organizer
  • Avoid: WP Optimize

These plugins cause issues that include not loading required resources or trying to optimize resources that are already optimal, thus creating performance issues and processing overhead both on the web server and client browser.

Rather than rely on seeming optimizations, we recommend to use appropriate caching and sound extensions that already come with their optimized resources. A sound setup does not need to rely on arbitrary optimizations.

As often, less is more also holds when it comes to plugins. Try to find the minimal set of plugins that provide the functionality required for a site. Don’t simply install more plugins just because everyone else does.

Avoid generic Database Modifications

↑ Back to top

It is strongly recommended to avoid any kind of optimizations or modifications regarding database tables and database entries created by the system and any of the official add-ons.

Modifying the database either manually or through any third-party optimization-oriented plugin can break the database, resulting in unexpected behavior for your site, including plugin malfunction and loss of data.

Database optimizations belong to the realm of expert database administrators who know what they are doing. Please note that any modifications to your database are the sole responsibility of your site’s administrators and the utmost care must be observed in taking any modifications to production.

Known Conflicts that affect Search Results

↑ Back to top

Plugin – Jetpack

If Jetpack Search is enabled, it can override the search results produced for products.

To avoid this, disable the search functionality in Jetpack to assure that it does not modify the results produced by the extension’s search engine:

Go to Jetpack > Dashboard > Performance and make sure that the option Jetpack Search is disabled.

Plugin – Post Types Order

This plugin provides an option which modifies the order of the search results produced by the Product Search Field widget and equivalent shortcode [woocommerce_product_search]. It also affects the results produced when the automatic search field replacement is active. To avoid this plugin modifying the order of the search results, disable the plugin or disable the option:

Disable the option Admin Sort which is found under Settings > Post Types Order.

Product images are missing

↑ Back to top

When you use live filters and the product images of the results are missing, then this is most likely due to a lazy loading implementation that is not compatible. Most lazy loading is coded in a way that is incompatible with image elements that are added dynamically on a page, and thus they fail to pull in the images after the live filter has found its matches. The recommended solution when this happens is to simply disable lazy loading of images.

General Plugin and Theme Compatibility

↑ Back to top

Where live filters are used, lazy loading provides no advantage as the products and their images are already loaded dynamically, according to the visitors choices. For those implementations of lazy loading that are actually compatible with dynamically built pages, there should be no issues though.

As of version 2.10.0, the search engine extension provides an API action that allows plugins and themes to be compatible with its live filters to selectively disable lazy loading. Plugins and themes that wish to be compatible, should listen to the woocommerce_product_search_signal_filter_response action and disable their lazy loading features during the request when this action is invoked.


↑ Back to top

Lazy Loading for images provided via Jetpack is fully compatible with WooCommerce Product Search as of version 2.10.0. If you are using a previous version, please update. Jetpack’s lazy loading for images can be turned on or off under Jetpack > Settings > Performance & speed using the option Enable lazy-loading for images.

Showing the lazy loading option in Jetpack
Jetpack’s lazy loading for images is compatible with WooCommerce Product Search’s live filters.


↑ Back to top

This theme provides a lazy loading option which should be disabled.

The7 > Theme Options > Advanced > Performance > Images lazy loading

Under Theme Options > Advanced > Performance, disable the option Images lazy loading.

Strange characters or corrupted output

↑ Back to top

In some cases it might be necessary to turn off accurate optimization when live filters are used. You will recognize that when you see strange characters in your product titles or descriptions after a live filter has been applied. Also when the output is corrupted (odd formatting), this might also be related to accurate optimization.

To solve this, go to WooCommerce > Settings > Search > General and disable the option “Use accurate optimization”. Save and try to apply a live filter. If there are further problems with the output, also disable the option “Optimize responses for filter requests”. Further details on these options are on the General settings documentation page.

Product attribute links don’t work as expected

↑ Back to top

The live attribute filters from the Product Filter – Attributes widget, the [woocommerce_product_filter_attribute] shortcode or the woocommerce_product_filter_attribute() function will produce links to product attribute archives when the style used is List or Inline.

When you try to visit these links and do not get the expected results, i.e. an archive page showing products that have the desired attribute, then you must enable archives for the product attribute in question.

To enable archives for a product attribute, go to Products > Attributes, edit the desired attribute and check the option Enable archives? – then go to Settings > Permalinks and click the Save Changes button.

The filters do not update the products displayed

↑ Back to top

Issues related to Templates

↑ Back to top

It is important that the template used to display products (shop page template, product archive template) applies the appropriate CSS classes to the containers:

  1. The container of the products shown on a shop page or product archive must have the .products CSS class applied. An alternative class can be specified using widget settings or parameters passed to the shortcode or API function, but we recommend to use the default class for consistency.
  2. The container for individual products displayed on the shop page or a product archive must have the .product CSS class applied. As with the above, there are settings that allow to specify an alternative although we also recommend to use the default again.

For the settings mentioned, please refer to the Product Filter – Search widget, the [woocommerce_product_filter] shortcode or its equivalent API function.

Indicative of these issues are the following browser console messages that would be displayed if the system cannot locate the corresponding containers:

  • Could not find the general Products Container, expected the selector .products
  • Could not find the individual Product Container, expected the selector .product

Issues related to Cache

↑ Back to top

If, after applying a search or filters, the products displayed do not change or products are shown that do not match, this could be related to the cache that is used on a site. Your site’s cache should differentiate requests that carry any of the following request parameters:

  • requests that have the ixmbd parameter
  • requests that have any of the following parameters: ixwps, ixwpss, ixwpse, ixwpsp, ixwpsf, ixwpst

If the caching mechanism that applies to pages and requests is not able to differentiate between requests that carry those parameters, adjust it so that requests which carry any of those parameters are not cached. You might need to contact the support team of your hosting provider for this.

Also note that the search engine includes a unique high-performance cache system, please review the Cache section for details.

The filters show duplicate translated terms with WPML

↑ Back to top

If you get duplicate entries from translated terms in your live filters, from the Product Filter – Categories widget, the Product Filter – Attributes or their shortcode equivalents, then you must enable the following option in WPML:

Go to WPML > Languages > Make themes work multilingual and enable the option Adjust IDs for multilingual functionality.

Combinations of filters are not applied

↑ Back to top

When you use the Product Filter – Search widget or the [woocommerce_product_filter] shortcode together with our live filter Widgets or Shortcodes, the widget’s option Update the Address Bar must be enabled / the shortcode’s update_address_bar attribute must be left at its default or set to "yes".

Filters and issues with site hosted on WP Engine

↑ Back to top

As of version 3 of the extension, it is likely that you do not need to disable object caching. If you have not yet updated the extension to version 3 or later, we recommend to update it on your staging site first, allow the search engine to rebuild its index and then enable object caching. Once you have done that, proceed to test your staging site with several searches and combinations of filters. If everything works fine, you can leave object caching enabled and deploy to your production site.

If you have object caching enabled and update the extension, please note that the notice to update the database may still appear for a while even though the database has already been updated. If you have already clicked the Update button, you do not need to click it again. The notice will go away once WP Engine’s object cache has been updated.

If you still see inconsistent results when you apply filters and your site is hosted on WP Engine, you might need to disable object caching or ask WP Engine support to disable caching for specific pages. For example, if you observe inconsistent results on a page where you are using the extension’s shortcodes, widgets or API functions, you can ask to have that specific page be excluded from caching while you can still take advantage of the performance benefits that object caching provides for the rest of your site.

Go to the Utilities section of your WP Engine dashboard, scroll down to Cache options and under Object caching click Disable and then click Save.  Now click Clear cache under Clear page cache.

It can take a few minutes for the changes to take effect, also make sure to clear your browser’s cache.

If your site’s error log or debug.log shows entries with errors, warnings or notices related to LONG QUERY or KILLED QUERY, add this to your site’s wp-config.php:

define( 'WPE_GOVERNOR', false );

This will prevent WP Engine restrictions to produce incorrect or no search results.

Filters and issues with site hosted on SiteGround

↑ Back to top

If you are using the SG Optimizer plugin, there might be issues in some cases with inconsistent results when filters are used due to incompatible caching. To circumvent the issue, you can exclude the relevant pages from caching using the option Exclude URLs. Add the URLs of relevant pages there, for example the shop page if live filters are used.

You might also need to disable SG Optimizer‘s Memcached option so that it does not conflict with the live filter results, although the need to do so might be reduced as of version 3 of the extension:

A further setting which should also be disabled is found under SG Optimizer‘s Frontend Optimization settings as it can also conflict with live filters. Disable the option to remove query strings from static resources:

Filters and issues with widgets using W3 Total Cache

↑ Back to top

Object Cache

↑ Back to top

In order for live filters to be able to function properly with W3TC’s object caching enabled, the cache group related to widgets should specifically be left out of the caching. This is done by adding widget under Performance > Object Cache > Non-persistent groups:

As this is not particularly related to the search engine’s filters, adjusting this is even useful when you have other widgets whose content changes according to the context.


↑ Back to top

All CSS styles and JS scripts used by the WooCommerce Product Search search engine are already minified and can be safely excluded in order to keep the live filters working. Under Performance > General Settings, go to the Minify section and choose Manual mode:

Then go to Performance > Minify and under Advanced section add the following entries in Never minify the following JS files:


Also add the following entries under Never minify the following CSS files:


The entries assume the standard plugin directory structure is used: wp-content/plugins.

If you are using customized plugin folders, adjust the paths accordingly.

Clicking the search button or hitting Enter leads to no products found

↑ Back to top

When you use the Product Filter – Search widget make sure that the option Update the Address Bar is enabled. When you use the [woocommerce_product_filter] shortcode, do not specify the update_address_bar attribute or set it to "yes".

Does it work with Elementor?

↑ Back to top

Yes. Here is a template of a custom shop page built with shortcodes and Elementor: WooCommerce Product Search Elementor Shop Example

Download and unzip the file. To use the template, go to Pages > Add New > Edit with Elementor > Add Template …

Then click the icon to import a template and choose the extracted file WooCommerce-Product-Search-Elementor-Shop-Example.json

Finally insert the template …

Now you have a fully customizable page built with the extension’s shortcodes, including live search and filters.

If you are using the Elementor Products widget and want the live filters to have an effect on the products displayed, you need to enable [products] shortcode filtering via the WPS_SHORTCODES_PRODUCTS_FILTER constant. This is because the Elementor Products widget uses the shortcode to render products.

Is it possible to search for custom fields or metadata, to find products by vendor, brand, manufacturer, part number … ?

↑ Back to top


If the information is related to products using related taxonomies or standard product data such as its title, ID, SKU or short description:

  • If the information is related to the products in the form of product categories, product attributes or tags, the search engine will automatically index the related information and find the products. In this case, you do not need to do anything in particular.

If the information is related to products using custom fields, the search engine’s indexer allows to add this, too, but you will need to provide the system with hints on what exactly it should index in addition:

  • Any additional data from custom fields can also be indexed, so that products can be found by arbitrary criteria stored for example as postmeta. We provide examples of how this is done here. Please note that this requires some basic knowledge of how WordPress filters are used, as the system provides the woocommerce_product_search_indexer_filter_content filter hook for this purpose. A qualified developer can easily help you to fine-tune the system based on the examples we provide.

The search engine integrates automatically with the WooCommerce Brands and WooCommerce Product Vendors extensions. Keyword searches for vendors and brands will result in matching products. For installations that have upgraded from a version prior to 2.20.0, the index must be rebuilt for all products to be indexed for brands and vendors. This is not required for new setups as of that version.

The woocommerce_product_search_compat_woocommerce_brands_index and woocommerce_product_search_compat_woocommerce_product_vendors_index filters allow to disable indexing of brands or vendors related to products.

Global Product Attributes vs. Custom Product Attributes

↑ Back to top

Only use global product attributes to relate products to their features. The search engine and its filters fully support features that are related to products using global product attributes, the system does not support the use of custom product attributes. We strongly recommend to only use global product attributes as the proper method to relate any product to its attributes, including those that are used on a single instance of a product. To learn more about how to create and use global product attributes, please refer to this section on Product Attributes.

Caching and performance based on memberships with Roles and Groups

↑ Back to top

As of version 3, the search engine supports caching based on WordPress roles and group memberships with Groups. Previously, it was often necessary to disable object caching or caching for users who are logged in, because the systems involved were not able to discern between content that can be served to any visitor, versus content that is visible to privileged groups of users only.

In those cases, we can now expect cached content to be served correctly, as the search engine supports role and group-based caching. This implies that in your caching system, you might now be able to enable options for object-caching or caching for users who are logged in.

Why and when this matters? It matters where you have products which must not be visible to everyone and access to them is restricted by role or group. If role or group-based caching were not supported, you would not be able to use caching, with the implication of slower responses while visitors browse your shop.

Whether your system may take advantage of this depends on the individual components used, specifically what caching system and whether it ties in with the extension’s related feature. We would certainly recommend to try things out on a staging or development site to make sure that with object caching or caching for logged in users things still work as expected. The overall benefit for your site’s performance can be substantial.

As of version 5, the extension includes a unique high-performance cache system, engineered to support fast and scalable operations. Review the Cache section of the documentation on the extension’s settings for details.

Potential Issues with Polylang

↑ Back to top

If the Product Search Field returns products in the default language only: Make sure that the Polylang Pro and Polylang for WooCommerce plugins are installed and activated. Ensure that you have added a translation for the product in question. If the product you search for does not appear in the results, edit it and add the missing translations in the Languages box.

If the search results page lacks the translated language slug and the search page is not translated: For example, when you reach the search results page after hitting enter in the Product Search Field or the Product Filter – Search field, and you are redirected to the search results page of the default language instead of the translated language. In that case, make sure that all products on your site are appropriately translated and that there is a translation of the search results page for every enabled language.

I have another question …

↑ Back to top

Have a question before you buy? Please fill out this pre-sales form.

Already purchased and need some assistance? Get in touch with the developer via the Help Desk.