Background information:
Alfresco's Repository clustering is built on Hazelcast, an open-source clustering library. Hazelcast announced changes to its Community (open-source) Edition (
https://hazelcast.com/blog/changes-to-community-edition/): starting with Hazelcast Platform 5.4, the Community Edition only ships major and minor releases (e.g. 5.4.0, 5.5.0) — patch releases are now Enterprise-only. Combined with Hazelcast's existing rule that a cluster can only roll forward one node at a time when nodes stay within the same minor version, this means any upgrade that moves to a new Hazelcast minor — which, on the Community Edition, is now how all fixes and improvements are delivered — falls outside what a rolling upgrade can support. That is the origin of the change described below.
Affects:
- Alfresco Repository25: 25.5.1+
- Alfresco repository 26: 26.2.3+
- Alfresco Share 26: 26.3.0+
- Alfresco Sync Service: 5.4.0+
Alfresco PaaS customers are not considered impacted.
What's changing:
Starting with the versions above, the Alfresco products upgraded their embedded clustering library. Previously the version used was 5.3.6. the new version Alfresco products depend on is 5.7.0. That makes rolling upgrades - where nodes running newer minor versions of the hazelcast library try to join a cluster tagged with a previous minor version - stall as the newer nodes are not able to join.
What this means operationally:
If you run a clustered Repository (more than one Repository node), a cluster of Alfresco Share nodes , or a cluster of Alfresco Sync service nodes, you need to make sure you deployment/upgrade script take this into account and that the old cluster is completely tiered down before you start spinning up new nodes.
If you deploy via our Helm charts, you should use the latest Alfresco umbrella Helm chart (10.9.0) so you don't need to change anything yourself. We've already adjusted the chart's deployment behavior to account for this.
Regardless of how you deploy or orchestrate Alfresco, the underlying constraint is the same, so the guidance below applies no matter your runtime platform.
- Upgrading requires taking the whole Repository cluster down and bringing it back up on the new version together, rather than replacing nodes one at a time while staying online throughout.
- Plan for a short, controlled maintenance window. The exact duration depends on your environment (number of nodes, startup time, etc.), but it is a clean, bounded stop/start rather than an open-ended rollout.
- If you deploy via our Helm charts, this is handled through a Recreate deployment strategy for the Repository component for this upgrade — all pods are stopped before any new ones start.
- If you manage your own deployment, apply the equivalent for your platform: stop all Repository instances before starting any on the new version. Do not attempt to replace nodes incrementally while others remain on the old version.
What happens if you don't follow this guidance:
If you attempt a rolling, node-by-node upgrade across this boundary anyway — whether that's a Kubernetes RollingUpdate, a load-balanced pool where you replace instances one at a time, or any other incremental replacement approach — here's what you'll observe:
- New nodes on the updated version will start up but fail to join the existing cluster. They'll retry for several minutes before giving up and crashing.
- Depending on your platform, crashed nodes may be automatically restarted, repeating the same failed join attempt indefinitely.
- The upgrade will not complete. You'll be left with a mix of old and new nodes, repeated startup failures, and no forward progress — not a clean failure, but a stuck state that typically requires manual intervention to resolve (for example, stopping everything and restarting cleanly on one version).
What you should do:
- Schedule a maintenance window for any upgrade crossing these version boundaries — treat it as a full-cluster restart, not a rolling upgrade.
- Do not attempt an incremental, node-by-node replacement across this boundary, regardless of your deployment platform.
- Watch release notes for future versions, since the same Hazelcast version policy will apply to later upgrades that move to a newer Hazelcast line, including patch versions.
- If zero-downtime rolling upgrades of the Repository cluster are a hard requirement for your organization, evaluate Hazelcast Enterprise licensing. Hazelcast Enterprise removes this constraint and supports true rolling upgrades across minor versions.
We are actively evaluating further options to improve this experience in future releases. If you have questions about planning this upgrade in your environment, reach out to your Hyland support contact.
