Common issues
If your symptom is specific to one feature, the troubleshooting section on that solution's page is more direct than this one.
Cross-cutting symptoms
| Symptom | Probable cause | First fix |
|---|---|---|
| Nothing happens after publishing | The site has not been republished since the script was installed | Republish in Webflow |
window.WfAlgolia is undefined | Tag missing, blocked by CSP, or type="module" absent | Verify your setup |
401 / 403 from algolia.net | Wrong key, or a key without the search ACL | Use the Search-Only key |
| Results come from an unexpected index | An ancestor supplies wf-algolia-index and the element inherited it | Set explicitly on the wrapper |
| A numeric range filter never narrows | The Algolia field is stored as a string | Re-index the field as a number |
| Sorting returns zero results | The replica name in your <option value="…"> does not match Algolia | Check Dashboard → Replicas |
| A filter search box does nothing | The facet is filter-only in Algolia | Set it to searchable — see below |
| A static page never appears in results | It is not a CMS item, so no collection mapping indexes it | Index it with the Algolia Crawler |
The searchable-facet trap
Searching within a facet's values uses Algolia's search-for-facet-values API, which only works when the attribute is declared searchable. A facet set to filter-only will filter correctly and fail silently at facet search.
In the Algolia dashboard: Configuration → Filtering and Faceting → Facets, then set the attribute to "Searchable (will return facets list)". Or in code:
index.setSettings({ attributesForFaceting: ['searchable(brand)'] });
What the console tells you
Every message is prefixed [wf-algolia]. The script warns and keeps going
rather than throwing, so in most cases the warning is your only signal that
something is misconfigured.
Configuration errors
These are thrown during startup, caught, and re-logged as
[wf-algolia] Initialization failed: followed by the message.
| Message | Meaning |
|---|---|
Script tag missing data-app-id attribute | No element on the page matches script[data-app-id] |
data-app-id and data-search-key are required | One of the two is present but empty |
Content and rendering
| Message | Meaning |
|---|---|
Failed to clone hit: | A result could not be rendered from your template |
populateCard text error: | A wf-algolia-text binding failed on one card |
populateCard html error: | A wf-algolia-html binding failed |
populateCard image error: | A wf-algolia-image binding failed |
populateCard link error: | A wf-algolia-link binding failed |
populateCard snippet error: | A snippet binding failed |
Blocked unsafe URL: | A field resolved to a URL scheme the script refuses to output |
The populateCard warnings name the binding that failed, which is almost always
a field name that does not exist on the record — check spelling and case against
a record in the Algolia dashboard.
Detail pages
| Message | Meaning |
|---|---|
Detail page missing wf-algolia-index | The detail wrapper has no index to query |
Detail page: no objectID found in URL or attributes | Nothing identifies which record to load |
Detail page: object not found for | The objectID was resolved but no record matched it |
Recommendations
| Message | Meaning |
|---|---|
recommend section missing model, index, grid, or template | One of the four required pieces is absent — the section renders nothing |
recommend: unknown model | The model name is not one Algolia recognises |
Note the wording: a recommendation section needs all four of a model, an index, a grid and a template. Missing any one produces this single message.
Filters and hierarchy
| Message | Meaning |
|---|---|
Cycle detected in hierarchy at | Cascading filter groups reference each other in a loop |
refreshChildGroup failed: | A dependent filter group could not reload its values |
refreshChildGroup (staged) failed: | The same, in deferred-apply mode |
standalone child re-scope failed: | A standalone child group could not re-scope to its parent |
facet-stat … | A facet-stat element is misconfigured |
static list … | A statically authored filter list is misconfigured |
Two reference-field symptoms have no console message at all, because nothing is misconfigured:
| Symptom | Meaning |
|---|---|
| A facet lists opaque IDs instead of names | The field is a Webflow reference. Map the referenced property in the app's field mapping. |
| A referenced item was renamed but search is stale | The parent item did not change, so the sync skipped it. Sync the collection on manual mode; on webhook mode it takes a Force reindex. |
Other
| Message | Meaning |
|---|---|
infinite-scroll loader rejected: | The next page failed to load |
Could not restart Webflow interactions: | Webflow's IX2 could not be re-initialised after a render |
Event handler error (…): | One of your own WfAlgolia.on() handlers threw |