FacetWP’s indexer is built to be very fast and reliable. However, indexing issues can occur in specific scenarios. Below we list the most common causes and fixes.

Fix a stalled indexer

FacetWP’s indexer can stall temporarily, for several reasons. If this happens, the first thing to do is wait a few minutes. FacetWP includes built-in resume functionality. It should resume automatically after a minute or two, if you keep the FacetWP settings screen open.

In specific circumstances, the indexer can get permanently stuck, often around the same percentage. These are the most common causes:

Fix memory exhaustion

The server running out of memory is the most common cause of a stuck indexer. This can be confirmed in the server’s error log. If you don’t have access to your server’s error log, you can confirm it as follows:

  • First enable WP_DEBUG and WP_DEBUG_LOG in your wp-config.php file.
  • Then, start a re-index by clicking the Re-index button, and wait until the indexer is definitively stuck.
  • After that, go to your site’s wp-content/ directory on your server and find the text file called debug.log. Open it in a text editor to view your server’s error log.
  • The log file can be very large. Check for errors near the bottom, around the time the indexer last got stuck, which is probably the last error logged. Most likely you’ll find a so-called “Fatal error” relating to memory, something like: “PHP Fatal error: Allowed memory size of {x} bytes exhausted (tried to allocate {x} bytes)”.

If you find there are memory exhaustion errors, the next step is to give WordPress more memory, while making sure this amount does not exceed the server’s memory limit.

Fix a .htpasswd login blocking resuming

To bypass PHP timeout issues, FacetWP’s indexer makes a series of HTTP requests to itself. If your site uses HTTP Basic Authentication (.htpasswd), you’ll need to tell FacetWP how to log in.

Add the following into functions.php or into the Custom Hooks add-on, and add your username/password to the code:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'http_request_args', function( $args, $url ) {
  if ( 0 === strpos( $url, get_site_url() ) ) {
    $args['headers'] = [
      'Authorization' => 'Basic ' . base64_encode( 'YOUR_USERNAME:YOUR_PASSWORD' ) // Change to your username and password
    ];
  }
  return $args;
}, 10, 2 );

Fix WP Engine settings

If you are hosting your website on WP Engine and you are experiencing problems with FacetWP’s indexer stalling or not indexing all your posts, see the fix below.

Fix a “The index table is empty” error

If you see a “The index table is empty” message during indexing, click the Re-index button again to restart the indexer. If that does not solve the issue, purge the index table and then re-index.

If that also does not clear up the error, check if any of the following situations apply:

  • The post types you are trying to index are not searchable. FacetWP only indexes searchable post types.
  • You have Polylang or WPML installed without FacetWP’s Multilingual add-on. If that is the case, install the add-on and re-index.
  • You only have one or more of these four facet types: Search facets, Pager facets, Sort facets and Reset facets. These facet types do not require any indexing to work. After indexing, the whole “Rows” column will be empty, and you will get a “The index table is empty” message, which is correct and expected behavior, as the index table is indeed empty.

Fix issues with indexing post types

If a certain post type is not getting indexed, or if you get a “The index table is empty” error when trying to re-index, the reason can be that this post type is not being indexed by FacetWP.

How to check indexable post types.
How to check indexable post types.

You can check which post types FacetWP indexes with the “Show indexable post types” action of the “Re-index” button in FacetWP’s settings.

The reason for a post type not being included in this list, is that FacetWP by default only indexes “searchable” post types.

For a post type to be “searchable”, the exclude_from_search argument of the register_post_type() function must be set to false. Post types can be registered with this function in your theme code, in functions.php, or with a custom post type plugin (like Advanced Custom Fields). In that last case, exclude_from_search will be a setting (in ACF it is located under: Post Types > Edit Post Type > Advanced Settings > Visibility > Exclude from Search).

As its name implies, the exclude_from_search argument also determines whether to exclude posts with this post type from the front-end WordPress search results. Keep this in mind when choosing how to fix this. There are basically three options:

Ways to fix indexing specific post types

The best way to fix indexing for your (custom) post type depends on how it is registered. With the first three options below, be aware that if you apply this, the posts of this post type will show up in the WordPress front-end search results. If you don’t want this, go with option 4.

  1. If you are using a plugin to register your custom post type, there will be a setting to disable exclude_from_search. In Advanced Custom Fields it is located under: Post Types > Edit Post Type > Advanced Settings > Visibility > Exclude from Search:
    Disable the 'Exclude From Search' setting when registering custom post types with ACF.
    Disable the ‘Exclude From Search’ setting when registering custom post types with ACF.
  2. If you have access to the code where your post type is registered, set the exclude_from_search argument of the register_post_type() function to false. If there is no exclude_from_search argument, you can add it:
How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
$args = array(
  //...other arguments
  'public'              => true,
  'exclude_from_search' => false, // add this, or if it already exists, set it to false
  //...other arguments
);
  1. If you don’t have access to the register_post_type() function, you can use a hook to set the exclude_from_search argument to false:
How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'register_post_type_args', function( $args, $post_type ) {
  if ( 'my_post_type' === $post_type ) { // change 'my_post_type' to your post type
    $args['exclude_from_search'] = false;
  }
  return $args;
}, 10, 2 );
  1. If you want to index and filter post types that you don’t want in your search results, it is also possible to force FacetWP to index non-searchable post types, with the facetwp_indexer_query_args hook. This hook can also be used to force FacetWP to index posts that have a post_status set to something else than public, like for example attachments.

Fix empty row counts

After indexing is complete, in the “Settings > FacetWP > Facets” overview screen’s “Rows” column, you’ll see the number of rows in the facetwp_index database table that have been indexed for that facet.

If a particular facet has no rows indexed, something has gone wrong while indexing the posts for that facet. Most of the time the solution can be found by checking the facet’s Data Source setting. Make sure that you select a valid data source and check if your posts have (valid) values saved for the selected field. After making corrections, re-index again to see the updated row counts. To check if a facet is working okay in general, you can test with its Data Source set to “Post Type” and re-index.

Note that four facet types will always have an empty “Rows” column: Search facets, Pager facets, Sort facets and Reset facets. These facet types do not require any indexing to work. They will also have an empty “Source” column:

Facet overview screen row counts
Expected row counts in the Facet overview screen.

This also means that if you have only one or more of these four facet types, the whole “Rows” column will be empty, and you will get a “The index table is empty” message, which is correct and expected behavior, as the index table is indeed empty.

Fix indexing issues with WP Engine

If you are hosting your website on WP Engine and you are experiencing problems with FacetWP’s indexer stalling or not indexing all your posts, try adding the following line to wp-config.php (not functions.php):

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
define( 'WPE_GOVERNOR', false );

WP Engine limits long queries (longer than 1024 characters) for performance reasons. The above line in wp-config.php prevents that.

Fix indexing issues with importing posts/products

If you are using WP All Import or WebToffee Import Export for WooCommerce to import posts/products, FacetWP’s automatic indexing can cause several issues when it runs during the import. Our recommendation is to disable the indexer temporarily, and then automatically trigger it once the import has finished. See these pages for more info and how to do this:

Fix indexing issues with bulk post editing

When bulk editing posts in the posts list edit screen, FacetWP’s automatic indexer is triggered. Normally this is a good thing. However, because bulk editing happens at a very high frequency, this can lead to 502 errors, caused by the server not being able to handle all necessary processing. This issue can specifically happen in multi-lingual setups with WPML or Polylang and FacetWP’s Multilingual add-on installed.

Disable automatic indexing.
Disable automatic indexing.

To prevent these issues, you could temporarily disable FacetWP’s “Enable automatic indexing” setting (introduced in version 4.3.4) before the bulk edit. Make sure to re-enable it when you are finished. To re-index after the bulk edit, just click the Re-index button.

To automate this, add the following code to your (child) theme’s functions.php. The code prevents the indexer from running during the bulk editing process. After the bulk edit has finished, the code schedules a one-time WP-Cron event that starts a full re-index:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_indexer_is_enabled', 'fwp_disable_indexer', 5 );
add_action( 'bulk_edit_posts', 'fwp_schedule_bulk_index' );
add_action( 'facetwp_indexer_cron_bulk_index', 'fwp_bulk_index' );

// Disable the indexer during bulk edit on post lists edit screen
function fwp_disable_indexer( $enabled ) {
  if ( isset( $_REQUEST['action'] ) && $_REQUEST['action'] === 'edit' && isset( $_REQUEST['bulk_edit'] ) ) {
    return false;
  }
  return $enabled;
}

 // Schedule one-time bulk index event
function fwp_schedule_bulk_index( $post_ids ) {
  wp_schedule_single_event( time(), 'facetwp_indexer_cron_bulk_index', array( $post_ids ) );
}

// Index posts after bulk edits
function fwp_bulk_index( $post_ids ) {
  foreach ( $post_ids as $post_id ) {
    FWP()->indexer->index( $post_id );
  }
}

Note that this solution uses WP-Cron, which is only triggered when there is front-end activity. Which means it can take time for the re-indexing to start. So if you don’t see it running, visit a front-end page. To check on cron activity, you can use the WP Crontrol plugin.

Fix indexing issues with very high post IDs

In the rare case that you have post IDs that are higher than 4294967295 (2^32-1), these posts will not get indexed properly because post IDs higher than this number cannot be stored in FacetWP’s indexing database table. This will lead to empty facets or facets with choices missing, depending on if all or some post IDs are above this limit.

Fortunately, there is an easy fix. Add the following code to your (child) theme’s functions.php:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_use_bigint', '__return_true' );

Fix slow indexing

If your website has a lot of content, indexing can take a long time. If you want to speed up the indexing process, see this section on our performance page about what influences the speed and some things you can do.

How to check indexable post types.
How to check indexable post types.

One simple way of speeding things up is to use the facetwp_indexer_query_args hook to limit indexing to the post types you are actually using with FacetWP. To check which post types FacetWP currently indexes, click the “Show indexable post types” button in the settings, as shown in the image on the right.

See also

Last updated: November 25, 2024