Faceted Search troubleshooting
Start with the symptom that visitors can reproduce. Change one variable at a time and reindex whenever the configuration affects indexed data.
No contexts are available
- Confirm Enable faceted search is active.
- Confirm the intended post type or taxonomy is public and has an archive where required.
- For saved collections, create or verify the query under Database queries.
A context is shown as disabled
A context needs an enabled context configuration and at least one enabled facet. Select Edit facets, add or enable a valid facet, save, and reindex.
Filters render but do not affect cards
- Match the facet IDs to the same context used by Listings (Feed).
- Set Use with faceted search? to Yes.
- For a custom query, select the same saved query in the listing.
- In Manual mode, add Faceted Search Submit with the correct Context ID.
Choices or counts are missing
- Verify the source key against real published content.
- Check term include/exclude restrictions and Zero-count choices.
- Confirm Counts is enabled if counts are expected.
- Save and run Reindex context.
For one problematic filter, follow Debug one facet.
Cards lose fields after filtering
Enable the required item under Indexed native fields or add its meta key under Indexed metas, then reindex. Mark a meta as Gallery only when the result template renders it as a gallery.
Sort does nothing
Use a supported sort value. Price and rating need compatible product data; distance needs a selected proximity point. A custom meta sort must exist under Managed meta sorting and use its declared ID.
Pager and results disagree
Use Faceted Search Pager, not the normal listing pagination. Confirm there is one intended result instance and one pager for it. Test from a clean URL without stale pf_page, pf_loaded_pages, or pfb_ parameters.
Map or proximity is unavailable
- Add the browser key under Settings → POM Theme → Integrations → Google Maps.
- Verify its allowed referrers and required Google Maps APIs.
- Check the location adapter and valid latitude/longitude values.
- Reindex after changing location data or configuration.
A shared URL does not restore
Confirm the context and generated facet IDs still exist. Recreate the state with visible controls and copy the new URL instead of editing pf_ parameters by hand.
Final verification
After correcting the configuration, test in a private window: initial results, every facet alone, one combination, empty results, reset, sorting, later pages, Back/Forward, and a copied URL.