Upgrading Apache HBase 2.4 to 2.5 or 2.6: Compatibility, Breaking Changes, Rolling Order and Rollback

The short answer

HBase 2.4 is end of maintenance. The HBase team announced 2.4.18, released on 25 May 2024, as the last patch release for the 2.4.x line, and pointed users at 2.5.x for longer support or 2.6.x for features such as TLS. The HBase 2.4 end-of-life page has the details.

Going from 2.4 to 2.5 or 2.6 is a minor-version upgrade. The reference guide treats minor versions as wire compatible and server-server compatible, and says rolling restarts are supported for upgrading to a minor or maintenance release. The work is in the edges: the Hadoop version underneath, the logging configuration, tracing, compression codecs, coprocessors and a few settings that 2.6 removes.

The current releases are 2.5.16 and 2.6.7, both from 1 October 2026. The downloads page marks 2.5.16 as the stable release. HBase 3.0.0 shipped on 5 August 2026, but it is a major version with its own upgrade notes, and this guide does not cover it.

2.5 or 2.6?

The Java and Hadoop rows come from the reference guide's support tables. The ZooKeeper versions come from each release's build file.

Our recommendation: pick 2.6 if you want JDK 17, built-in TLS for RPC or the backup and restore tooling, and your Hadoop is already on 3.3.5 or later. Pick 2.5 if Hadoop is on 3.2.3 to 3.3.4 and moving it is a separate project. Either way, do not skip the Hadoop check below.

Check Hadoop first

The Hadoop matrix is where a 2.4 cluster is most likely to fail the upgrade. HBase 2.4 is marked as working with Hadoop 3.1.1 and later, all of 3.2 and all of 3.3. The newer lines are stricter:

• HBase 2.5 raised the minimum Hadoop 2 version to 2.10.2 (HBASE-27299) and the minimum Hadoop 3 version to 3.2.3 (HBASE-27148). Hadoop 3.1.x, 3.2.0 to 3.2.2 and 3.3.0 to 3.3.1 are marked as not working.
• HBase 2.6 raised the Hadoop 3 minimum to 3.3.5 (HBASE-28277). All of Hadoop 3.2 and 3.3.0 to 3.3.4 are out.
• Hadoop 3.4 is supported from HBase 2.5.11 and 2.6.2.

Two related points from the guide. In distributed mode the Hadoop jars in HBase's lib directory must match the Hadoop running on the cluster. And from 2.5.2 onwards the project publishes separate -hadoop3 binaries. From 2.5.11 and 2.6.2 those builds track the latest supported Hadoop 3 release, which the guide says greatly reduces the number of known CVEs shipped in the binaries. Use the hadoop3 tarball if you run Hadoop 3.

If the cluster is still on Hadoop 2.10, it can stay there for this upgrade, but the guide recommends Hadoop 3 because no 2.x release has followed 2.10.2. The Hadoop end-of-life guide covers the options for that move.

What changes between 2.4 and 2.6

2.6 also brings native TLS for the RPC layer, with plaintext and TLS allowed side by side so an existing cluster can switch without downtime, plus experimental backup and restore, HDFS erasure coding for table data, quota improvements and a Prometheus metrics endpoint. Turn these on after the upgrade has settled, not during it.

Coprocessors and other server-side code

The reference guide is clear about the limits. Coprocessors, custom filters, replication endpoints and other plugins built on LimitedPrivate interfaces only get source and binary compatibility between patch versions. Classes marked Private, or with no annotation, can change at any time. A minor upgrade from 2.4 can therefore break a coprocessor that compiled cleanly for years.

• List every coprocessor loaded through hbase.coprocessor.* settings and table descriptors.
• Rebuild each one, and each custom filter, balancer or replication endpoint, against the target version's jars.
• Exercise them in staging with production-like data, including region splits, merges and moves.
• Check Phoenix, or any other layer that installs its own coprocessors, for a release that supports your target HBase line.

ZooKeeper

HBase 2.4.18 bundles ZooKeeper 3.8.4. HBase 2.5.16 and 2.6.7 bundle 3.8.6, which is still one release behind ZooKeeper 3.8.7. If HBase manages its own ensemble (HBASE_MANAGES_ZK=true), the upgrade moves that ensemble from 3.8.4 to 3.8.6. If you run a separate ensemble, HBase's dependency rules say an HBase upgrade does not require a ZooKeeper upgrade, so keep the two changes in separate windows. The HBase and ZooKeeper page lists what each release ships.

Rolling upgrade order

1. Bring 2.4 to 2.4.18 if it is not there already.
2. Confirm Hadoop against the target line's matrix, and replace the Hadoop jars in HBase's lib directory with the ones from your cluster, or use the matching hadoop3 tarball.
3. Prepare configuration: start from the target version's conf directory, port hbase-site.xml and hbase-env.sh, write log4j2.properties, and remove HTrace and removed WAL writer settings.
4. Record state: the balancer, normalizer, snapshot cleanup and split/merge switches, replication peers, RS groups, quotas and table descriptors.
5. Disable the balancer with balance_switch false. The guide assumes the balancer is off while graceful_stop.sh runs, and advises managing it yourself because the script does not turn it back on if it exits early.
6. Upgrade the backup masters, then the active master. The guide's general advice is backup masters first, then the active master, then RegionServers. In our practice, once a new master has been active, we do not start an old one again outside a planned rollback, because 2.6 moves some switch state into the master local region.
7. Roll the RegionServers one at a time, or rack by rack. graceful_stop.sh --restart --reload moves regions off a server one at a time, stops it, restarts it and moves the regions back. bin/rolling-restart.sh is a template the guide says is not explicitly tested, so adapt it before relying on it.
8. Upgrade REST and Thrift gateways, then clients. Old clients can talk to upgraded servers under the wire compatibility rules.
9. Re-enable the balancer and compare the recorded state.

Test plan

• Run the whole upgrade in staging with production configuration, coprocessors and a copy of real tables.
• Read and write every table through the client paths you use: Java client, REST, Thrift and Phoenix.
• Check that each column family's compression codec loads, especially anything that used XZ.
• Trigger flushes, compactions, splits and merges and watch for coprocessor errors.
• Check replication to every peer, and that bulk loads still work.
• Kill a RegionServer under load and confirm regions reassign.
• Confirm your log shipping and dashboards still find what they expect after the log4j2 change.
• Take and restore a snapshot.

Rollback

The reference guide documents rollback, not downgrade. Rollback restores the old version and loses every change made since the upgrade began, and it only works if you prepared before starting.

• Before the upgrade, document every replication peer and take a backup of the HBase data, for example with hadoop distcp of the root directory as the guide describes. A rollback that is not an all-service rollback loses configured replication peers.
• Keep the 2.4.18 packages and configuration on every node.
• During the RegionServer roll, a node that misbehaves can be stopped and restarted on 2.4.18, since minor versions co-exist in a cluster.
• After the masters have moved, the safe route back is the guide's rollback procedure: stop HBase, restore the data directory, clear the HBase znode and start the old version. Expect lost locality until compactions run.
• Do not enable new features, such as file-based store file tracking, filesystem replication peer storage, erasure coding or TLS-only RPC, until the rollback window has closed. HBASE-28457 added a version field to the file-based tracker so an older release fails loudly on its files, which shows the project expects this to go wrong if you try.

If you cannot upgrade yet

A 2.4 cluster often waits on something else: a Hadoop 3.1 platform that 2.5 and 2.6 no longer support, a vendor coprocessor, or an application team that cannot retest this quarter. OSSeva ships patched, signed HBase builds for 1.7, 2.2, 2.3 and 2.4, with the bundled ZooKeeper patched in the same build, delivered through Maven, Docker and tarballs. Assure adds a master, RegionServer and ZooKeeper quorum review, a Kerberos, ACL and coprocessor exposure audit, a Hadoop and ZooKeeper version map for every cluster, a SOC 2 and HIPAA attestation package and an upgrade plan to 2.5, 2.6 or 3.0. Operate adds 24/7 region, compaction and RPC latency monitoring, a 15-minute P1 response, a named senior HBase engineer and execution of the rolling upgrade with the ZooKeeper quorum kept intact. See HBase extended support, Apache HBase support, the HBase end-of-life tracker and HBase support options.

Common questions

Can I upgrade HBase 2.4 directly to 2.6?

The reference guide does not require a stop at 2.5, and minor versions are wire compatible. Check that your Hadoop is 3.3.5 or later first, because 2.6 does not support Hadoop 3.2 or 3.3.0 to 3.3.4.

Is a rolling upgrade from 2.4 to 2.5 or 2.6 supported?

Yes, under the guide's compatibility rules for minor versions. Upgrade the backup masters, then the active master, then the RegionServers.

Does HBase 2.6 run on Java 17?

Yes. The guide lists JDK 8, 11 and 17 as supported for 2.6. For 2.5, JDK 17 support is preliminary, and 2.4 does not support it.

Do HBase 2.4 clients work with a 2.6 cluster?

Under the wire compatibility rules, an old client can connect to an upgraded cluster. Plan to upgrade clients anyway, and to move them off ZooKeeper-based connections before HBase 4.