Troubleshooting Guide

Enable Debug Mode

FacetWP has a special Debug Mode that can help with diagnosing issues, by providing low-level information about pages with facets. In our support we use also use Debug Mode, which is why we ask you to enable it before submitting a ticket.

To turn on Debug Mode, go to FacetWP > Settings > General, enable the “Debug Mode” setting, and then click “Save changes”:

Using Debug Mode to diagnose issues

When Debug Mode is enabled, FacetWP adds extra data into the browser Console. To access it, go to a front-end page with facets, open your browser’s inspector, go to the Console tab, and type:

FWP.settings.debug

The Console will then show a JavaScript object with a lot of useful debugging data, including the facet and listing template settings, query arguments and SQL. The object can be clicked open to reveal all sub items, which can be further clicked open:

All separate items can also be accessed directly, by typing them into the Console:

FWP.settings.debug; // all debug info

FWP.settings.debug.hooks_used; // the names (and paths) of relevant custom hooks
FWP.settings.debug.query_args; // query arguments
FWP.settings.debug.sql; // the raw SQL
FWP.settings.debug.row_counts; // the number of posts indexed for each facet
FWP.settings.pager; // pager data
FWP.template; // the name of the listing template used
FWP.settings.debug.template; // info about the listing template used

A good starting point for debugging is opening or typing:

FWP.settings.pager

This will output information about the post and page counts, looking like the image on the right. Are the counts what you are expecting them to be?

Next, look at the output of:

FWP.settings.debug.query_args

Does the post_type match what you’re expecting? Now check the the other query arguments, like posts_per_page. Is it the same as what you have set in your query arguments or in the Listing Builder’s Query tab settings?

If the post/page counts look wrong, or the query arguments are not what you expect them to be, then FacetWP is likely not using the right query. See the solution below.

To see the exact SQL statement that FacetWP is using for the listing query, type:

FWP.settings.debug.sql

Also here, a wrong post_type or number of posts per page (the second number in for example LIMIT 0, 10) are indicators of FacetWP detecting the wrong query. Sometimes the SQL doesn’t match up with the query arguments, hinting at a conflict with another plugin.

Fix an incorrectly detected query

There can be multiple – often invisible – queries running on a page, added by custom code, your theme, or other plugins. Sometimes it happens that FacetWP’s automatic query detection latches on to the wrong (archive) query.

When this is the case, the results often look okay on initial page load, but are wrong after filtering. You can check if this is happening by using FacetWP’s Debug Mode.

There are several ways of fixing this issue:

Enable “Strict query detection”

The first thing to try is to enable the “Strict query detection” setting in Facetwp > Settings > General. As its name implies, this setting uses a stricter way of detecting the right query, which in most cases will solve the issue.

If enabling “Strict query detection” does not work, you can also force FacetWP to specifically ignore the incorrectly detected query:

Force FacetWP to ignore a query

Let’s say that by using FacetWP’s Debug Mode, you have determined that FacetWP is incorrectly using a query with the post_type argument set to edd_wish_list.

You can force FacetWP to ignore this specific query by using the facetwp_is_main_query filter.

Add the following code to your (child) theme’s functions.php, and replace edd_wish_list with the name of your post type that is incorrectly detected as the main query to use:

add_filter( 'facetwp_is_main_query', function( $is_main_query, $query ) {
    if ( 'edd_wish_list' == $query->get( 'post_type' ) ) {
        $is_main_query = false; // ignore this query
    }
    return $is_main_query;
}, 10, 2 );

The “FacetWP was unable to auto-detect the post listing” error

FacetWP was unable to auto-detect the post listing

If you’re seeing this error it’s because FacetWP can’t find a suitable query. This usually happens when you have a custom WP_Query on a standard WordPress page. To let FacetWP detect the custom query, you have to add facetwp => true to the query arguments. See this section for more information.

See also

• Using the Right Query
• The facetwp_is_main_query hook
• Listing Templates
• Using a WP Archive Page
• Using a Custom WP_Query
• Using a Page Builder
• Using the Listing Builder
• How to customize WordPress archive queries