Discovery Troubleshooting
This page provides troubleshooting guidance for common issues encountered when implementing the Discovery plugin in Bloomreach Content.
ON THIS PAGE
Installation
| Symptom | Cause | Resolution |
|---|
| Required HST service is not available: org.bloomreach.forge.discovery.site.platform.HstDiscoveryService | The site web application is running with an older plugin version than the one installed. | Rebuild and redeploy the site web application using the current plugin version. |
| Picker endpoint returns 404 at {cms}/ws/discovery/picker/search | The brxm-discovery-cms dependency is missing from the CMS classpath, or the picker daemon module has not started. | Verify that the dependency is present and review the CMS log for the plugin's startup message. See Installation for details. |
| Bundled templates not found / blank pages | The site's HST configuration does not inherit from hst:default. | Add the missing brxdis-* template entries to your site's template configuration. Reference the plugin's bundled Freemarker files. |
| Category highlight, product detail, or recommendation components display empty output with no error in logs | org.bloomreach.forge is not included in the hst-beans-annotated-classes scan list in web.xml. HST locates the JCR node but cannot map it to a Java class, so getBean() returns null. | Add classpath*:org/bloomreach/forge/**/*.class to the hst-beans-annotated-classes context parameter in WEB-INF/web.xml. See Headful setups - bean scanning. Restart the site web application after making this change. |
Configuration and credentials
| Symptom | Cause | Resolution |
|---|
| ConfigurationException: Discovery accountId is required | Credentials are not configured in any location checked by the plugin (environment, system property, or JCR). | Set BRXDIS_ACCOUNT_ID, BRXDIS_DOMAIN_KEY, and BRXDIS_API_KEY. |
| Product grid renders empty with no error | The accountId or domainKey values do not match your Discovery account. | Confirm both values in your Discovery dashboard. |
| A custom product attribute (for example, brand) is missing from results | The field is not included in the configured field list. | Add the field to brxdis:defaultFieldList (global) or discoveryDefaultFieldList (per channel). See Configuration. |
| Picker displays blank product names | The picker's title field does not match the actual field name in your catalog. | Set brxdis:pickerTitleField to the correct field name. See Picker field mapping. |
Search & category pages
| Symptom | Cause | Resolution |
|---|
| Category page renders nothing | No category is configured, and no URL parameter or path segment provides one. | Pin a category using the document picker, or verify that the page receives the expected URL parameter. |
| A warning banner appears in Channel Manager preview, but the page appears normal to visitors | This is expected behavior. Configuration warnings display only in preview mode; production visitors see an empty state without an error. | No action required unless you need to resolve the underlying configuration issue. |
Recommendations
| Symptom | Cause | Resolution |
|---|
| Recommendation widget renders empty | The Discovery widget has no results, or the widget ID does not match an ID in your account. | Check the widget's status in the Discovery dashboard. |
Recommendations always use v1 even though authKey is set | The authKey value is not reaching the plugin. Review which configuration layer (environment, system property, JCR, or channel override) is in use. | See Configuration for details. |
Visual search
For troubleshooting visual search, refer to the table in Recommendations & Visual Search. Visual search configuration often requires correct mount placement.
Pixel tracking
| Symptom | Cause | Resolution |
|---|
| No pixel events appear in Discovery analytics | Tracking is disabled at the deployment or channel level, or consent gating is blocking events. | Check the deployment kill switch, the channel's Pixel Tracking settings, and any consent cookie or provider configuration. See Pixel Tracking & Consent. |
| All events display the same IP or generic browser in analytics | The headless frontend is not forwarding the visitor's real IP, User-Agent, or locale headers. | Configure header forwarding in your SPA server layer. |
Still stuck?
Enable DEBUG level logging for the plugin's package and review the log output for the relevant request path and error messages. Most failures will indicate a clear cause, such as a missing credential, incorrect ID, or unreachable Discovery endpoint, when debug logging is enabled.