Moving Hyperledger Besu to JDK 25

Why moving Hyperledger Besu to JDK 25 is a platform change, not a library bump

If you run permissioned Besu nodes, you must move them to JDK 25 before you adopt Besu 26.6.0 or any later release, because the 26.6.0 release notes state that Besu requires JDK 25 to build and run. The supported route is to step through the 26.x calendar releases in order, reviewing the release notes for each version rather than jumping straight to the newest build. The releases page lists 26.7.0 (July 13, 2026), 26.8.0 (August 19, 2026), 26.9.0 (September 25, 2026) and 26.10.0 (October 16, 2026), so your plan should assume a new release roughly every month and confirm each step against the notes before you schedule it.

Treat the change as a platform change because the runtime touches more than one JVM. The JDK version determines the base image your containers are built from, the host packages your validators and RPC nodes depend on, the JAVA_OPTS heap and garbage collector settings you tuned for an older runtime, and the build toolchain used for any custom plugin. A plugin compiled against an older JDK may not run on the new one, so the plugin build and the Besu image must move together. Ask your platform team to inventory every place a Java version is pinned, including CI runners, configuration management roles and any hardened base images your security team approves.

Before you change anything on a production validator, run the new JDK and a staging Besu build against a copy of your node data and confirm that the node starts, peers and produces or imports blocks. Record the exact JDK build, Besu version and plugin versions in your change record so that a rollback can restore the previous combination. Because later 26.x releases may change the database format, the rollback path depends on a backup taken before the move, a point the upgrade sibling sections cover in detail.

What changes in the Besu 26.x releases and what each change means for operators

This table lists the Besu changes that affect permissioned networks from 25.6.0 through 26.10.0, with the release that introduced each one. Read each row as a question: does this change touch my nodes, my configuration or my stored data, and what must my team do before the upgrade window.

Change	Release	Impact	Action needed
JDK 25 required to build and run Besu	26.6.0 (June 4, 2026)	Hosts, base images and build pipelines on older JDKs will not run the new release.	Confirm JDK 25 availability on every host, image and build agent, and update JVM options and plugin builds.
Clique consensus removed	26.4.0 (April 22, 2026)	Pure Clique networks can no longer start or produce blocks on this release.	Confirm no network still uses Clique, and plan a consensus migration before upgrading.
Tessera privacy removed	25.6.0 (June 4, 2025)	Privacy features that depended on Tessera no longer work in current releases.	Identify any private transaction flows and choose a replacement, such as a plugin or fork.
Onchain permissioning removed	25.6.0 (June 4, 2025)	Smart-contract-based allowlists no longer apply on upgraded nodes.	Move access rules to local node and account permissioning files and verify them on every node.
EEA and PRIV privacy RPC groups removed	25.7.0	Client applications calling these RPC methods will receive errors.	Audit application and integration RPC calls, and update any that depend on EEA or PRIV methods.
Proof of work and fast sync sunsetting	Announced by LF Decentralized Trust	Networks relying on these features need a planned change before they lose support.	Confirm your network uses QBFT or IBFT 2.0, and confirm no node depends on fast sync.
Bonsai database auto-upgrade on first start	26.10.0	Older Besu versions cannot open an upgraded database, so downgrade needs a prior backup.	Take and verify a full backup of node data before the first start on 26.10.0.

How the JDK 25 requirement reaches hosts, images and builds

On hosts installed from system packages or a tarball, Besu uses whatever Java runtime the start script resolves, so the host's default JDK matters as much as the Besu version. Besu 26.6.0 requires JDK 25 to build and run, so a host that still resolves JDK 21 or earlier will fail at startup or be left on an older Besu release. Teams often find that several Java versions are installed side by side, and the wrong one wins on a service restart.

Installed runtime version: confirm that the runtime the service unit actually launches reports JDK 25, not only that a JDK 25 package exists on the host.
Alternatives and environment variables: check the default Java alternative and any JAVA_HOME set in the systemd unit, profile scripts or configuration management roles.
JVM flags: review every flag in JAVA_OPTS or the unit file against the 26.6.0 release notes, and remove any flag that the notes say changed or no longer applies.
Rolling order: upgrade the runtime on one validator first, restart it, and confirm it peers before touching the rest.
Rollback path: keep the previous runtime package available so a host can be returned to its prior state if the new runtime causes problems.

Before each restart, confirm the exact flag changes in the 26.6.0 release notes rather than assuming them from earlier versions.

What to inventory and back up before the first 26.x start

Before any node runs a 26.x release, the team needs a complete picture of what it runs and a way back if the upgrade fails. The cards below cover the inventory, the database backup, key protection, plugin compatibility, staging and post-change checks that connect those steps.

Full node and config inventory

List every node with its role (validator, boot or RPC), host, container image, JDK version and launch options. Include the permissions configuration file, since node and account permissioning rules decide which peers and accounts a node accepts after restart. Record the files each node reads so you can compare them after the upgrade. Illustrative example: a validator that starts with a JVM option set by an older image may fail on JDK 25 without any change to Besu itself.

Bonsai database backup first

The Bonsai database upgrades automatically on first start, and older Besu versions cannot open the upgraded database. Take a backup of each node's data directory while the node is stopped or from a consistent snapshot, and confirm you can restore it on a test host. Treat this backup as the only rollback path. Store it outside the host that runs the node so a failed host does not take the backup with it.

Protect the node private key

The local node private key file is not encrypted. Anyone who reads the file can impersonate the node, so restrict file permissions, limit which service accounts can read the data directory, and keep copies in access-controlled backup storage. Where your policy requires hardware-backed keys, confirm whether a security module plugin such as the HSM plugin fits your setup before the cutover, not during it.

Custom plugins and HSM versions

List every custom plugin and the Besu version it was built and tested against, including the HSM plugin version. Plugins are compiled against the Besu plugin API, so a JDK 25 build of Besu can break a plugin that was built for an earlier runtime. Rebuild each plugin with the JDK 25 toolchain, confirm the pinned Besu version, and keep the previous plugin artifacts so you can roll back with the node.

Staging that mirrors production

Build a staging network with the same node count, roles, validator set, peer topology, permissions files and storage layout as production. Run the 26.x upgrade there first, including a restart of the validators in the order you plan to use in production. Staging only proves the change if its topology matches, so document every known difference and decide whether it changes the result.

Check JSON-RPC auth and metrics after the change

After the first 26.x start, confirm that JSON-RPC authentication still loads its credentials file or validates JWTs against the expected public key, and that the metrics endpoint enabled with --metrics-enabled still answers on its port (default 9545). A changed launch option or image path can disable either silently. Check both on every node, because monitoring that goes dark after the upgrade hides later faults.

The upgrade sequence for a permissioned Besu network on JDK 25

This sequence moves each Besu node onto a JDK 25 runtime and a target Besu release without losing quorum, with a backup or rollback point and a gating check before every change.

Confirm current version and legacy settings
The network operator records the Besu version on every node and searches each node's configuration and genesis for settings tied to removed features: Clique consensus, Tessera privacy, onchain permissioning, and the EEA and PRIV privacy RPC API groups. Besu 26.4.0 removed Clique, so a pure Clique network cannot start on current releases, and the 25.x removals mean any leftover privacy or onchain permissioning settings must be dealt with first. The step closes with a written inventory per node. Nothing moves until every removed setting has a named owner and a replacement plan.
Build and validate the JDK 25 base
The platform team builds the host or container base image on JDK 25, since Besu 26.6.0 requires JDK 25 to build and run. They carry over JVM options such as heap sizing and garbage collector flags, then confirm the runtime version inside the same image that will run Besu. The gate is a Besu start on a throwaway data directory against a test genesis, with the version output and startup logs checked. Keep the previous image tagged so the old runtime remains available as a rollback point.
Rebuild custom plugins for the target release
The development team rebuilds each custom plugin, including any HSM or security module plugin, against the target Besu release and the JDK 25 base. Plugins compiled for an older runtime or an older plugin API may fail to load, so each build is tested for load and startup, not just compilation. Confirm the plugin version pairs with the Besu version in the release notes. The gate is a clean plugin load in the staging image, with the build artifacts and version pairs recorded in the change record.
Back up node data before any change
Each node's data directory, node private key file, permissions configuration and startup configuration are backed up and the restore is tested on a separate host. The Bonsai database upgrades on first start in Besu 26.10.0 and older versions cannot open the upgraded database, so this backup is the only route back for that release. Store keys with the same access controls as production. The gate is a successful test restore of at least one node, with the backup checksums recorded.
Upgrade one staging node and verify
The operator upgrades a single staging node to the JDK 25 image and target Besu version, then checks that it peers with the other staging nodes, produces or imports blocks in line with the chain, and publishes metrics to Prometheus when metrics are enabled. Review the logs for plugin errors and permissioning rejections. The gate is a stable run over a period the team sets in its own test plan, with peer count, block height and metric scrapes confirmed. If any check fails, the node reverts to the backed-up data and the previous image.
Roll validators one at a time
Validators are upgraded one at a time, with a fresh backup and a tagged rollback image taken before each node changes. Before restarting a validator, the operator confirms the remaining validators still hold quorum for QBFT, so the chain keeps producing blocks throughout. After each node comes back, the team checks peering, block production, and that the node is following the head of the chain before moving on. Only the next node in the order starts when the current one passes these checks.
Close the change record and upgrade non-validators
After all validators run the target release, the operator upgrades the remaining RPC and boot nodes using the same backup, check and rollback pattern. The change record is completed with the node inventory, backup locations, plugin versions, test results and any deviations. Confirm with the vendor or your own test results which release notes items apply to your configuration before the change is closed. Done means every node reports the same target version and the record is signed off by the network owner.

How to test the move and plan rollback before the Bonsai upgrade

A JDK change is usually reversible only while the database has not been opened by a newer Besu. Once a Besu release that auto-upgrades the Bonsai database has started on a node, an older Besu cannot open that database, so a JVM rollback alone will not bring the node back. Before any production host moves to JDK 25, take a backup of each node's data directory and confirm that you can restore it onto the previous runtime and Besu version. A backup that has never been restored is an assumption, not a rollback plan. Ask your team to document where backups live, who can trigger a restore, and how long a restore takes on your storage.

Run the move first on a staging network that mirrors production: the same Besu version, the same genesis and consensus settings, and the same node roles. Check that each node starts on JDK 25 and reaches the chain head, that block import keeps pace, and that the node re-establishes peer connections to the expected static peers and validators. Confirm that JSON-RPC authentication still works with your credentials file or JWT public key, and that requests without valid credentials are refused. If you enable metrics with --metrics-enabled, confirm that Prometheus can scrape the default port 9545. Load every custom plugin, including any HSM plugin, and confirm that each one starts against the target Besu version.

Record the results of each test in a change record, including the backup identifier used for the restore rehearsal. For the database-specific steps, including the Bonsai auto-upgrade behavior and how to protect against an accidental downgrade, follow the sibling pages on upgrading Hyperledger Besu to the 26.x releases and on planning rollback before the Besu 26.10 database upgrade. Those pages describe the database changes; this section covers the JDK move itself.

What makes a JDK 25 move longer or shorter

This table lists the factors that change how much work a JDK 25 move takes on a permissioned Besu network, with the reason each matters and what to confirm before planning. Read each row against your own estate, since the largest drivers are usually node count, the number of custom images and plugins, and whether removed features are still in use.

Driver	Why it matters	What to confirm
Number of nodes and validators	Every host runs the JDK 25 runtime, and validators must restart in a sequence that keeps quorum online, so more validators means more restart windows and more peering checks.	Full node and validator inventory by site, plus the agreed restart order with each consortium operator.
Custom images and base OS versions	Each image that bundles Besu or a JDK needs rebuilding and retesting, and each base OS may ship a different JDK package or repository source.	Count of images, their base OS versions, and where each JDK 25 build is sourced and approved internally.
Plugin count and HSM plugin pinning	Plugins are built against the Besu plugin API, so a plugin compiled for an older runtime may need rebuilding, and an unpinned HSM plugin can fail after the move.	Number of plugins, whether each one builds on JDK 25, and the HSM plugin version pinned to the target Besu release.
Use of removed features such as Clique or privacy	Besu 26.4.0 removed Clique, and earlier releases removed Tessera privacy and onchain permissioning, so a network still relying on them needs a migration before or alongside the runtime change.	Whether any node still uses Clique, Tessera, EEA or PRIV RPC groups, or onchain permissioning, and the owner of each dependency.
Custom JVM options and heap settings	Flags tuned for an earlier JDK may be ignored, deprecated or behave differently, which affects memory use and garbage collection on busy validators.	Current JVM options in each service definition and whether they were tested on JDK 25 in staging.
Data size and backup time	The Bonsai database upgrades on first start and older Besu versions cannot open it, so backup size and restore time set how long a safe rollback point takes to prepare.	Database size per node, backup method, and a timed restore test on a copy of production data.
Change control and regulator evidence	Operators in regulated entities usually need approved change records, test evidence and a rollback plan before a runtime change, which adds review cycles.	Your change policy, approval levels, required evidence format, and whether the consortium or regulator must be notified.
Staging availability	A staging network that mirrors production versions, plugins and data shape lets the team find JDK issues before a live restart, and its absence shifts risk into production.	Whether staging runs the same OS images, JDK build, plugins and a recent copy of chain data, and who can book it.

Questions teams ask before moving Besu to JDK 25

What does moving Besu to JDK 25 cost, and what drives the fee?

The fee follows from the written scope, not from a fixed rate for the JDK change itself. The main drivers are how many hosts, container images and CI pipelines need rebuilding, whether you run Besu from source, a vendor package or a custom image, how many plugins you maintain and must rebuild against the new runtime, and how much staging evidence your change process requires. Recurring costs are mostly ongoing support and the next monthly release cycle, not the JDK move itself. DeployOpen does not publish a price list. Ask any partner, including DeployOpen, for a quote that lists each host and image type, each plugin, test environments, change-record deliverables and what is one-time versus retainer-based.

How long does a JDK 25 move take on a permissioned Besu network?

The timeline is set by the number of environments to upgrade, the number of plugins to rebuild, and the change windows your operators can use. Besu requires JDK 25 to build and run from release 26.6.0 (June 4, 2026), so any node still on an older release will need both the runtime change and the Besu release to be planned together. Schedule time for staging tests, a rolling restart order for validators, and sign-off from every consortium operator. Your partner should state the duration in the written scope once the environment inventory is complete. Ask for the milestones and which ones depend on your approvers.

Can our own platform team move Besu to JDK 25 without a partner?

Often yes, if your team already owns the Besu build, the container pipeline and the validator runbook. The JDK change itself is a configuration and image change, but the work that usually slows teams is confirming plugin builds, updating JVM options, and proving that validators restart cleanly on a staging network that matches production. Assess your team against that list. If the same people also run the network, a partner can take the staging and evidence work while your staff keep control of production changes. Either way, keep the change record and a tested backup in place.

What do we need to provide before the work starts?

Expect to provide access and a clear inventory before any build begins. The usual list includes:

Read access to the Besu deployment definitions, container images, CI pipelines and host configuration
A staging network that mirrors production topology, with validator and boot node counts that match
Named approvers for each operator, and the change windows each one allows
Plugin source code, build files and the Besu versions they are tested against
Your backup location and the procedure for restoring node data

Without these, the scope cannot be estimated and the rollout date will move.

Does a rolling restart keep a Besu network live during the JDK change?

A rolling restart can keep the network live if you restart validators one at a time and keep enough of them online to maintain consensus. For QBFT, the network needs more than two-thirds of validators to keep producing blocks, so the restart order and the count of nodes down at once must be checked before each step. Confirm peering between nodes after each restart and watch block production before moving to the next node. Confirm the exact behavior of your Besu release and consensus settings in the Besu documentation and on your own staging network before relying on it in production.

What happens if a custom Besu plugin does not build on JDK 25?

A plugin that fails to build blocks the rollout for every node that needs it, so treat it as a planned work item rather than a surprise. The fix depends on the cause: a dependency may need a newer version, a build tool may need an update, or the plugin may call an API that changed in the release you are moving to. Plugins such as an HSM plugin should be pinned to a Besu version that has been tested, and the Besu upgrade notes should be checked for API changes. Keep the previous working image available so you can roll back the plugin build without rolling back the whole network.

Who approves the change, and what evidence do auditors expect?

The approvers are normally the network operators, your change advisory board, and the owner of the affected key material. Each approver should see the release notes reviewed, the staging test results, the rolling restart plan, and the rollback steps. Regulated operators also keep a record of what changed, when, and who signed off. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue any audit report or attestation. Ask your auditor which records they will request before the change window opens.

Which official sources to read before scheduling the change

Read the Besu 26.6.0 release notes before you set a date for the JDK 25 change, because they are the source that states Besu requires JDK 25 to build and run. The notes were published on June 4, 2026. Use the Besu releases page on GitHub to confirm which calendar release you are moving to and to check every release between your current version and the target. Besu ships roughly monthly, so a plan written against one release can be out of date within weeks. Record the release you tested, the JDK build you tested it with, and the date you checked the page.

Use the Besu documentation at docs.besu-eth.org as the reference for the settings your change touches. Confirm the JDK version your container base image, systemd unit or Kubernetes image provides, and check any JVM options in your startup scripts against the current configuration guidance. Also confirm whether any plugin you load, including an HSM plugin used with the --security-module option, publishes a build for the target Besu version and the JDK 25 runtime. Where the documentation is silent on a point, put it on your verification list rather than assuming the old setting still applies.

Read the LF Decentralized Trust blog post on sunsetting Tessera and simplifying Hyperledger Besu alongside the release notes. It explains the removal of features such as Tessera privacy, onchain permissioning and proof of work consensus. The JDK change often arrives in the same window as these removals, so a team that upgrades only the runtime can miss a configuration that no longer starts. Ask your platform owners to list every flag, plugin and consensus setting in use, then check each against what the blog and release notes say was removed before the change window is booked.

How DeployOpen works on this

DeployOpen treats the move to JDK 25 as a planned change to the hosts, images, pipelines and plugins that run Besu in your infrastructure. We scope the work in writing first, then build and test it in staging before any validator is restarted, so your team keeps control of timing and change records.

How we scope

Inventory every Besu host, container image, build pipeline and plugin that must move to the JDK 25 runtime
Confirm the Besu version targeted and review the 26.6.0 release notes with your team before work starts
Agree deliverables, exclusions and timelines in a fixed-scope written document ahead of any build work

How we build

Rebuild base images and JVM options for JDK 25 and test startup, peering and RPC behavior in a staging network
Rebuild or re-test custom plugins, including any HSM security module plugin, against the Besu version you will run
Document the rollback path, including a verified backup before any Bonsai database change in later releases

How we hand over

Deliver a runbook for rolling restarts in an order that keeps validators online and peering intact
Provide updated image definitions, pipeline configuration and JVM option files under your version control
Walk your operations and security teams through verification results and the change record you need to keep

How we support

Ongoing support, upgrades and continuous testing are available as a retainer for future Besu calendar releases
Retainers can cover monitoring of release notes, staging rebuilds and plugin compatibility checks for each new version
Ask any supplier, including DeployOpen, to confirm support boundaries and response expectations in the written scope