This FAQ addresses common issues, patterns, and best practices for upgrading the Content, based on an analysis of tickets raised by Bloomreach customers and internal support teams. It includes troubleshooting for upgrade errors, plugin compatibility, security vulnerabilities, CMS usability, feature regressions, and best-practice recommendations across major and minor releases.
General Upgrade Questions
Q: Can I upgrade directly between major/minor versions, or must I upgrade sequentially?
- You cannot directly upgrade between major versions (e.g., 13 to 16). Major version upgrades must be performed sequentially (e.g., 13 -> 14 -> 15 -> 16), as each major release includes database scripts and schema changes that require a step-by-step update process. Each individual major upgrade requires a complete stop/start deployment of the application.
- You can upgrade directly between minor versions (e.g. 15.3.2 to 16.2), provided there is no specific step in the upgrade notes indicating a mandatory intermediate version. Always perform a complete stop/start deployment; rolling deployment is not supported for such upgrades.
Q: What are the main best practices to follow for a Content upgrade?
- Always review the official release notes for your target version before upgrading, paying close attention to breaking changes, dependency updates, and known issues.
- Test your upgrade in a non-production environment, ideally by copying your production database to a safe UAT or QA environment first.
- Use Content's configuration verifier to catch any conflicts or mismatches between production and development environments, especially if local or manual changes may have been made.
- Ensure you are deploying with repo.bootstrap=true and perform a stop/start deployment, not rolling deployments, when making major changes that affect repository initialization.
- After the upgrade, monitor logs closely for warnings or errors, and verify that all expected modules and plugins have loaded.
- If you encounter issues with third-party plugins, check for updated, compatible versions.
Q: How can I revert back a major version deployment (for example from 16.x.x to 15.x.x)
Once upgrade is started, the only way to properly downgrade is:
- Stop all server instances
- Restore a database backup from before the upgrade
- Delete all server Lucene indexes (repository folders)
- Deploy the old application and start the servers
Common Issues and Resolutions
1. Console Errors Related to Pendo/Usage Statistics
Symptoms:
JS errors in browser console calling app.pendo.io, even after disabling usage statistics. - Unauthorized request errors in logs related to Pendo endpoints.
Resolution:
These errors are fixed in Content v15.7.2, v16.2.0, and newer versions. Upgrade at least to these versions and review your content security policy (CSP) settings. In custom environments, you may also need to update or restrict CSP policies post-upgrade.
2. Engagement Plugin and Collector Issues After Upgrade
Symptoms:
Post-upgrade to 16.2+, exceptions/warnings about Engagement Plugin or EngagementCollector during login or in logs.
Resolution:
Upgrade to Content 16.3.0 or later, where related errors are downgraded to warnings. Complete removal of the Engagement plugins and characteristics from /hippo:configuration/hippo:frontend/cms/hippo-targeting and /targeting:targeting will eliminate the issue in 16.2. It is safe to ignore if you see only warnings.
3. Experience Manager/Content Editor UI Breakage
Symptoms:
- Overlay buttons, drag-and-drop, or document edit panels fail to load or behave erratically after upgrade.
- Frequent loading spinners, menu items become unresponsive, or persistent freezes after switching between Content and Experience Manager.
Known Cases and Fixes:
- Several UI regressions and freezes (especially in Chromium-based browsers) have been fixed in Content versions 16.2.0, 16.3.0, 15.7.1, and equivalent 14.7.x releases.
- Upgrade to at least these releases if you are impacted.
- SPA overlays/users: Always use the latest compatible versions of the SPA SDK and React SDK, as outdated SDKs can cause compatibility issues.
-
For drag-and-drop in ordered lists and compound/multi-value field editing in the right-side panel: Content versions 16.3.0 and 16.4.1 include key fixes; if still experiencing issues, confirm plugin and SDK versions.
Tips: - If certain document fields or edit panels vanish from the sidebar after upgrade to Content v16.1+, check for known bugs in your target version; upgrades to the next minor/patch may be needed.
4. Security Vulnerabilities & Third-Party Library Upgrades
Symptoms:
- Vulnerable dependency scans flag libraries (Spring, Tomcat, Lucene, Commons FileUpload, etc.) as high/critical severity.
- False positives may arise when a vulnerability affects a library you depend on, but not the code paths you use.
Please see list of known false positives here:
https://xmdocumentation.bloomreach.com/about/false-positive-vulnerabilities.html
Resolution:
- Bloomreach regularly integrates third-party security fixes in new Content releases. Upgrading to the latest Content versions is frequently necessary for the latest library versions.
- Overriding library versions via custom builds is unsupported and may cause backwards compatibility problems.
- A public list of open vulnerabilities is not maintained; known false positives are documented in the [Bloomreach documentation site] and customers are encouraged to upgrade and report findings via support channels.
- If required, coordinate upgrade timelines with Bloomreach Support; fixes for critical dependencies are prioritized for upcoming releases.
5. Plugin Compatibility (Forge, S3, hst-springsec, etc.)
- Always check if a compatible version of each Forge/community plugin is available for your Content release, especially after breaking changes (e.g., the switch from javax to jakarta namespaces or major Spring upgrades in v16).
6. Deployment Issues (Pods, Docker, Local/DEV vs. QA)
- If HST modules/services do not start in containerized or custom Docker deployments, but work in developer mode, review your shared library configuration and ensure all expected dependencies are present.
- Recreate shared-lib-component.xml including all dependencies documented for your Content /target version.
Plugin Support & Community Add-ons
- Major upgrades (15→16) often break older plugins (e.g., S3 Manager, hst-springsec) until a compatible version is published. Always check for updated releases on the Forge site or reach out to Bloomreach for Professional Services support. Community plugins are maintained best-effort and may lag behind platform releases.
Known Feature/Regression Fixes and Their Versions
- Engagement Plugin error threshold: 16.3.0
- CMS freezes, menu unresponsiveness: Fixed in 16.2.0, 16.3.0, 15.7.1
- Experience Manager document editor regressions for content blocks, optional compounds, OpenUI fields: Fixed incrementally in 16.3.0–16.4.1.
- Security dependency CVEs: Ongoing; check release notes for your Content version and planned fixes for upcoming versions (often 16.4/16.5).
- Folder-context-menus bug: Plugin releases 6.1.1 (v15) and 7.1.1 (v16).
Security and Compliance
- Security vulnerabilities reported by automated scans are triaged by criticality and business risk. False positives due to library transitive dependencies are common, especially if the vulnerable code path is not reachable in Content. Major framework upgrades (e.g., Spring Boot 2→3, Spring 5→6) are included in major Content versions for security reasons. For special compliance needs, reach out to support or your account manager.
Upgrade Support Resources
- Release Notes by Version: Review all features, bugs, and security fixes before upgrading.
- Bloomreach Documentation Site: Sign up as needed for access to upgrade guides, configuration examples, and migration notes.
- Professional Services/Support: For complex upgrades, project implementations, or migrations, contact Bloomreach Professional Services.
- Community and Forge Plugins: Check plugin compatibility before and after major upgrades. Consider contributing fixes if possible.
For further details refer to official upgrade & troubleshooting documentation or contact Bloomreach Support.