One of those errors may be preventing FacetWP from loading properly. Please contact your developer, or
open a support ticket mentioning the specific error message you see.
To open the console, right click anywhere on your front-end facet page and select "Inspect Element". Then click the "Console" tab if it isn't already active.
As a last resort, we need to rule out any possible issues caused by 3rd party plugins. Try (temporarily) disabling all non-essential plugins.
Essential plugins are ones like
ACF, CPT UI, and WooCommerce (the base plugin). The more plugins you can rule out, the better.
If so, FacetWP could be
detecting the wrong query, so the next step involves using Debug Mode to see which query FacetWP is using.
If the issue happens on
archive pages and your site has caching enabled, it's also possible that the
fwp-loop HTML comment tag -- which FacetWP requires -- is getting stripped out. Make sure your caching plugin is set to
not remove HTML comments.
If so, FacetWP isn't able to find a suitable query. Make sure you're using a
By default, FacetWP does
not pass authentication data to the server.
If your listing depends on
is_user_logged_in() or similar authentication checks, you will need to
use this hook to include authentication data.
To open the console, right click anywhere on your front-end facet page and select "Inspect Element". Then click the "Network" tab and select "XHR".
Below are some common response codes:
200 - Success 401 - Unauthorized (maybe due to a site lockdown or .htpasswd?) 403 - Forbidden (blocked by a firewall or service like Sucuri?) 404 - Not Found (is the REST API disabled?) 5XX - Server errors (often a PHP fatal error or server ran out or memory. check your web server's PHP error log for clues)
Make sure you've added
"facetwp" => true to the query arguments.
Also check to see if this is an
archive page (look for an "archive" class on the <body> tag). For archive pages, we strongly recommend
modifying the archive query, instead of creating your own.
Elementor and Beaver Builder are the only builders we
officially support at this time.
Also, if you're using Beaver Builder on an archive page, make sure your listing module's
Query setting is set to "Main Query".
While we don't yet officially support Oxygen, try manually adding the CSS class
facetwp-template to the container element surrounding your listing grid. According to some customers, this works well when using Oxygen on existing archive pages.
Please open a support ticket (Settings > FacetWP > Support, within your site dashboard). Make sure that
Debug Mode is turned ON.
Debug Mode provides extra helpful information about queries, facets, etc.
FacetWP is likely
not detecting the right query, and debug mode can help determine
why. Follow the instructions further down on this page to use debug mode.
If everything else works fine, it could be that the
facetwp-template CSS class isn't in the right spot. FacetWP will only modify content
inside this container element.
Learn more »
If you're using WooCommerce, try
adding this code into your (child) theme's functions.php.
If your layout looks different after an
Learn more »
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:
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:
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:
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:
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.
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.