Why a Hyperledger Besu upgrade to 26.x needs a plan before the first restart
Upgrading a permissioned Besu network to the 26.x releases needs a written plan before any node restarts. The reason is that 26.x changes three things at once: the runtime, the data on disk and the consensus setup. Besu requires JDK 25 to build and run, as stated in the 26.6.0 release notes. Clique consensus was removed in 26.4.0, so a pure Clique network can no longer start or produce blocks. The Bonsai database also upgrades automatically on first start, and older Besu versions cannot open the upgraded data. Each of these changes lands on a different team: platform engineers own the JDK and hosts, validator operators own the consensus configuration, and the data owners own the backups.
The supported path depends on the release each node runs today, so the first task is an inventory. For every node, record the current Besu version, the JDK it runs on, the database format, whether the chain uses QBFT or any legacy consensus setting, and any plugins or custom images that embed Besu. Nodes that are already on a recent release follow a different sequence from nodes still on a build older than 26.4.0. Ask the network's maintainers or your release owner to confirm the exact upgrade steps between your current build and the target 26.x release, and check them against the Besu releases page before scheduling anything.
Treat the upgrade as a change window with a rollback decision made in advance. A backup taken before the first 26.10.0 start is the only reliable rollback path, because the upgraded database cannot be opened by an older Besu build. Agree who approves the upgrade, what evidence is captured before and after each node restart, and which staging environment proves the sequence works on a copy of your chain data. Confirm these points with your validator operators and infrastructure team before the change is approved, since they set how long the network can tolerate nodes being offline.
What changes in the 26.x releases and what each change asks of operators
This table lists the 26.x-era changes and earlier removals that affect permissioned Besu networks, with the impact of each and the checks your team should perform before upgrading. Read each row against your current client version and node configuration, since the action needed depends on what you run today.
| Change | Impact | Action needed |
|---|---|---|
| JDK 25 required from 26.6.0 (June 4, 2026) | Besu 26.6.0 and later require JDK 25 to build and run, so hosts, container images and build pipelines on older JDKs will fail to start the client. | Confirm every node image, host and plugin build uses JDK 25 before the binary is changed, and test startup in staging. |
| Clique removed in 26.4.0 (April 22, 2026) | Besu can no longer start or produce blocks on pure Clique networks, so a network still on Clique stops at this release. | Confirm the chain uses QBFT or IBFT 2.0 and plan any consensus migration before moving any node to 26.4.0 or later. |
| Bonsai database auto-upgrades on first start (26.10.0, October 16, 2026) | The database is upgraded automatically on first start, and older Besu versions cannot open the upgraded database, so rollback depends on a backup. | Take and verify a full node data backup before the first 26.10.0 start, and record which nodes have been upgraded. |
| Tessera privacy and onchain permissioning removed in 25.6.0 (June 4, 2025) | Teams still on 25.x that rely on Tessera or smart-contract-based permissioning must move to a replacement before they upgrade past this release. | Confirm no node config or contract still references Tessera or onchain permissioning, and move permissioning to local files. |
| EEA and PRIV RPC API groups removed in 25.7.0 | Applications or scripts calling EEA or PRIV JSON-RPC methods will fail after this release. | Search client applications and monitoring scripts for EEA and PRIV method calls and replace them before upgrading. |
| Proof of work and fast sync sunsetting announced by maintainers | These features are being removed from the codebase, so networks or sync procedures that depend on them will need changes in a future release. | Confirm your nodes use neither proof of work nor fast sync, and check the maintainers' sunset timeline in the release notes before each upgrade. |
Which upgrade path applies to your current Besu version
Nodes already on a 25.x release have the shortest path to the 26.x line, but the 25.x line still carries removals that affect configuration. Start by confirming your exact current version and the target release on the Besu releases page, then read every release note between the two. The notes are the authoritative list of what changes at each step.
- Plan the JDK change: Besu 26.6.0 requires JDK 25 to build and run, so schedule host or image updates alongside the binary change.
- Check privacy RPC use: Besu 25.7.0 removed the EEA and PRIV privacy RPC API groups. Nodes below 25.7.0 may still expose them, so check client applications and monitoring for calls to those groups.
- Check your database setting: if your node uses Bonsai, the database upgrade in 26.10.0 runs automatically on first start and older versions cannot open it, so take and test a backup first.
- Rehearse on staging: run the same version sequence on a test network with a matching validator set before touching production.
- Confirm the stop points: whether a 25.x node can move directly to 26.x in one step is a question for the release notes for your versions.
Record the version you will stop at for each stage and the release note that drives each stop.
Nodes on 26.x releases earlier than 26.4.0 have already passed the 25.x removals, but they still face the later changes. Upgrading from these versions means crossing 26.4.0, where Clique consensus was removed, and then 26.6.0, where JDK 25 becomes required. The 26.7.0, 26.8.0, 26.9.0 and 26.10.0 releases follow on a roughly monthly cadence, so the move may span several planned stages.
- Clear the Clique check first: Besu 26.4.0 removed Clique consensus, so confirm the network is not running pure Clique before crossing that release (see the Clique tab).
- Prepare the runtime before 26.6.0: the JDK 25 requirement applies from 26.6.0, so host, container image and plugin builds need to be ready before that stage.
- Back up before the database step: the Bonsai database upgrade in 26.10.0 is one-way, so take and verify a backup before that stage.
- Schedule stages, not one jump: map each release between your version and your target to a separate change window with its own verification.
- Upgrade validators one at a time: restart validators in sequence and check peering after each restart so the network keeps producing blocks.
Read the notes for every release from your current version forward and map each breaking change to a named stage.
Besu 26.4.0 removed Clique consensus, and Besu can no longer start or produce blocks on pure Clique networks. A binary upgrade alone will stop those nodes, so the consensus change has to be planned and tested before any node moves to 26.4.0 or later. The LF Decentralized Trust project page says Besu supports proof-of-authority consensus through QBFT or IBFT 2.0 for permissioned networks, which are the usual targets for a Clique network.
- Inventory consensus settings: confirm every node and genesis file uses Clique before work starts, and identify any mixed setups separately.
- Choose the target consensus: confirm whether QBFT or IBFT 2.0 fits your validator set and operating model, and agree the validator addresses with every operator.
- Stop before 26.4.0: no node should cross 26.4.0 while still configured for Clique. Confirm in the release notes which earlier version still runs Clique and record it as the last stage on that path.
- Agree a switch point: all operators need the same milestone for the consensus change, plus any genesis or configuration changes that go with it.
- Rehearse on a copy of the chain: test block production, peering and recovery on a copy before the production switch.
Confirm the migration method against the Besu documentation and the release notes for your exact versions before scheduling any node.
Besu 25.6.0 removed the Tessera privacy feature and onchain permissioning, and 25.7.0 later removed the EEA and PRIV privacy RPC API groups. Networks that still depend on these features need replacements in place before their nodes reach the removal point. The maintainers have described the reasons for sunsetting these features in the LF Decentralized Trust blog, and they suggest plugins or community forks for teams that still need the removed functions.
- Map every dependency: list each use of Tessera, onchain permissioning contracts, and EEA or PRIV calls across nodes, applications and monitoring.
- Move node permissioning to local files: Besu local permissioning uses a node permissions file to restrict connections to known participants and an account permissioning file for onboarding and restricting actions. The permissioning topic covers the design.
- Decide on privacy: choose a replacement for Tessera-based privacy, such as a plugin, a community fork or another design, and treat it as a separate project with its own testing.
- Update client calls: change any application code that calls EEA or PRIV methods before the node that removes them is upgraded.
- Test the replacements: verify permissioning and privacy behavior on staging nodes before changing production.
Confirm which removed features your network uses and the version at which each stops working in the release notes before you choose a path.
Backups, inventory and staging work that must happen before any restart
Upgrading to 26.x changes things that cannot be reversed with a binary rollback alone. The work below gives the team a known good state to return to, a complete picture of what the nodes depend on, and a place to test the change before validators restart.
Verified Bonsai database backup
Besu 26.10.0 upgrades the Bonsai database automatically on first start, and older Besu versions cannot open the upgraded database. A backup taken before the upgrade is the only rollback path. Confirm each node's backup is complete, stored off the host, and restored successfully on a scratch machine before any validator is touched. Record the Besu version and the block height at which the backup was taken.
Node configuration and permissions inventory
List every configuration file, startup flag and environment variable each node uses, along with its node and account permissions files. Removed features such as Tessera privacy, onchain permissioning and Clique consensus can appear in older configs and will stop a node from starting or producing blocks. Confirm each setting still exists in the target release and that permissions files match the consortium's current allowlists.
JSON-RPC consumers and authentication settings
Identify every application, monitoring job and operator script that calls the node's JSON-RPC API, and record how each one authenticates. Besu supports a credentials file or JWTs validated against a public key, and it does not terminate HTTPS natively, so TLS is handled by a proxy you run. Confirm which clients will break if the API changes, and test authentication against the staging node.
Custom images and JVM options rebuilt on JDK 25
Besu 26.6.0 and later require JDK 25 to build and run. Any custom container image, base image or host package set still pinned to an older Java runtime must be rebuilt, and JVM options tuned for earlier runtimes should be reviewed. Confirm the image builds, starts a node and passes a health check on JDK 25 before the rolling restart plan is finalized.
Plugins checked for compatibility
Each custom plugin and any vendor plugin, such as an HSM plugin, must be confirmed against the exact Besu version in the plan. Plugins built against removed or reorganized APIs may fail at startup, and a plugin that loads but misbehaves can be harder to spot than a crash. Confirm each plugin's supported Besu versions with its owner, pin the tested version, and record the result in the change file.
Staging network mirroring validators and peering
Build a staging network with the same validator count, consensus settings, node roles and peering topology as production, using copies of the inventoried configuration. Run the upgrade there first, confirm blocks keep producing, and check that nodes reconnect after restarts. A staging network with fewer validators or simpler peering will not show the quorum and connectivity problems that matter in production.
The upgrade sequence for validators, RPC nodes and the staging network
This sequence moves a permissioned Besu network onto a 26.x release in an order that keeps consensus alive, gives every node a rollback point, and proves the result before the next node changes.
Review release notes and removed features
The network lead and the client engineering owner read the release notes for every version between the current build and the target 26.x release, then list each removed or changed feature the network depends on. Clique removal in 26.4.0, the earlier removals of Tessera, onchain permissioning and the EEA and PRIV RPC groups, and the JDK 25 requirement from 26.6.0 all belong on that list. Done means each dependency has an owner and a decision: keep, replace, or retire. Confirm the target version against the GitHub releases page before the plan is locked.
Rebuild the runtime on JDK 25
The platform team rebuilds the Besu runtime, container images or host packages on JDK 25, since Besu 26.6.0 requires it to build and run. They also rebuild any plugins against the new runtime, revisit JVM options, and confirm the startup scripts pass the right flags. Done means every node image starts on JDK 25 in a non-production environment and reports the expected Besu version in its startup log. Keep the previous image tagged so it remains available as a fallback.
Upgrade the staging network and run tests
The staging network mirrors the production topology, including validator count, permissioning files and RPC authentication. Operators upgrade staging first, then run the consensus, transaction, permissioning and API tests that the business depends on. Important check: the staging copy of the Bonsai database is upgraded and cannot be reverted, so staging should start from a restored copy of production data, not the live nodes. Done means the test suite passes on the upgraded staging network and the results are recorded for the change record.
Back up each node before the database upgrade
Each node operator takes a full backup of the node data directory and the node key file before the production change starts. The 26.10.0 release notes state that the Bonsai database auto-upgrades on first start and older Besu versions cannot open the upgraded database, so this backup is the only rollback point for that step. Store backups off the host, record checksums, and test one restore on a separate machine. Done means every node has a verified backup and the restore test has succeeded.
Confirm peering and validator quorum
Before any node restarts, the operators confirm that every validator is connected to its peers, that the permissioning configuration matches across the consortium, and that the active validator set is producing blocks. A network that has already lost two-thirds of its validators cannot tolerate another restart, so this check is a hard stop. Done means the peer count, validator list and latest block height are recorded and agreed by all operators.
Upgrade validators one at a time
Validators restart in a planned order, one at a time, with the rest of the set kept online so that at least two-thirds of validators remain available throughout. After each restart the operator waits until the node rejoins, produces or imports blocks, and reconnects to peers before moving to the next validator. Rollback point for each node is its backup from the preparation step. Done means every validator reports the target version and the chain has advanced continuously through the window.
Upgrade RPC and other nodes
Once validators are on the new version, the operators upgrade RPC nodes, observers and any other nodes behind load balancers. Drain each node from the load balancer, upgrade it, check its sync status and API responses, then return it to service. Authentication settings, including the credentials file or JWT public key, should be checked during this step, since client applications depend on them. Done means every node serves requests with the expected version and authenticated calls succeed.
Verify metrics and logs across the network
The final step confirms that the upgraded network is observable. Operators check that Prometheus targets are up on each node, that the Grafana dashboards show block production and peer counts, and that logs from every node reach the central pipeline with the new version string. Any alert rules that rely on removed metrics or removed features should be reviewed. Done means the monitoring checks pass, the change record is closed with the rollback points used or not used, and the network owner signs off.
How to test the upgrade in staging and decide whether to roll back
Staging has to prove that a 26.x node behaves like the node it replaces, not merely that it starts. Confirm first that the node runs on JDK 25, since Besu 26.6.0 requires it to build and run, and that the same JDK is used in the image or host that will go to production. Then check that the node syncs, joins the expected validator set and produces or imports blocks as QBFT validators should. Confirm the validator set in staging matches the production genesis and that peers reconnect after restart. Stop the staging run if any of these checks fail, because a fault found here costs far less than one found on a validator in production.
Next, test the surfaces the upgrade should not have changed. Call JSON-RPC with the same credentials file or JWT setup used in production, and confirm that unauthenticated and invalid requests are still refused. Confirm the node permissions configuration still allows and denies the same peers and accounts. Check that metrics still answer on the default port 9545 when --metrics-enabled is set, and that your Prometheus scrape job finds the target without changes. Load each plugin, including any HSM plugin used with --security-module, and confirm it starts against this Besu version. Record the results as evidence for the change record.
Agree the rollback decision before production starts, not during the incident. Because the Bonsai database auto-upgrades on first start and older Besu versions cannot open it, rollback means stopping the node, restoring the pre-upgrade backup, starting the prior release and letting the node rejoin the network. Write down go or no-go criteria in advance, such as the checks above passing, a validator staying in sync within an agreed window and no rejected blocks, and name the person who calls the rollback. Confirm with your own environment how long a restore takes, since that figure drives the window in which you can still roll back. Rehearse the restore on staging so that the backup is known to be usable.
What makes a 26.x upgrade take longer for one network than another
This table compares the factors that stretch or shorten a Besu 26.x upgrade across permissioned networks that look similar on paper. Read each row as a question to answer about your own network before you set a window, since the same release can take a day on one network and weeks on another. The main takeaway is that database size, validator count, custom tooling, and the number of coordinating organizations usually matter more than the release itself.
| Driver | Why it matters | What to check |
|---|---|---|
| Bonsai database size and backup throughput | The Bonsai database upgrades automatically on first start and older Besu versions cannot open it, so a verified backup is required before any node moves. Larger databases take longer to back up and restore. | Measure database size on each node and time a full backup and restore in staging. Confirm the backup target has enough capacity and that restores have been tested. |
| Number of validators and quorum margin | QBFT needs two-thirds of validators online to keep producing blocks. A small validator set leaves little room for a node that fails to come back during a rolling restart. | Count validators and note how many can be offline at once. Confirm the restart order keeps quorum at every step and that the team can roll back a single node. |
| Customized images, JVM options and deployment tooling | Besu 26.6.0 requires JDK 25, so custom container images, startup scripts and JVM flags built for older runtimes must change before the node can start. | Inventory base images, JVM options, Ansible roles or Kubernetes manifests that set Java versions. Confirm each one builds and starts on JDK 25 in staging. |
| Plugins such as the HSM plugin pinned to older builds | Plugins are built against Besu's plugin API, so a plugin pinned to an older Besu version can block the upgrade or change signing behavior after it. | List every plugin and its tested Besu version. Confirm the plugin vendor or build supports the target release before scheduling. |
| Remaining Clique, Tessera or onchain permissioning dependencies | Besu 26.4.0 removed Clique, and earlier releases removed Tessera privacy and onchain permissioning. Networks still using these features need a migration before they can upgrade at all. | Search genesis files, node configs and scripts for Clique, Tessera, onchain permissioning and removed privacy RPC groups. Confirm each replacement path is planned and tested. |
| Number of organizations coordinating restart windows | Each operator controls its own nodes and change process. More organizations mean more approvals, more calendars and more chances for one party to slip a window. | Map every operator, its change board and its freeze periods. Agree the restart order, communication channel and escalation contact in writing before the window. |
| Monitoring and log pipelines that must be revalidated | Metric names, log formats and dashboards can change between releases, and alerts that stop firing can hide a stalled node after the upgrade. | Confirm metrics endpoints, Prometheus scrapes, Grafana dashboards and log parsers still work on the target version. Test alert rules with a deliberate fault in staging. |
Questions operators ask before upgrading Besu to 26.x
What does it cost to upgrade Hyperledger Besu to 26.x?
No price is published here, and the cost depends on the written scope. The main cost components are the staff hours spent on release note review, JDK 25 host and image changes, configuration review, backups, staging tests, rolling restarts and post-upgrade checks, plus any custom plugins that must be rebuilt. Most of this is one-time work for the upgrade itself. Recurring costs come from keeping pace with the roughly monthly release cadence, which you can plan as a retainer or handle in-house. Ask any provider for a quote that lists each activity, who performs it, which environments are included, how many nodes are in scope, and whether plugin or HSM work is priced separately.
How long does a Besu 26.x upgrade take?
The schedule is set by the number of environments, the number of nodes and validators, how many custom plugins or integrations must be retested, and how many organizations must coordinate restarts. Besu ships roughly monthly, with releases listed for 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 the target release also affects timing. Ask for a written timeline with milestones for staging tests, the backup checkpoint, the first rolling restart and the post-upgrade review, and confirm which dates the provider has built in around change freezes.
What does the upgrade need from our own team?
Your team needs to own the decisions and the production access. Someone must review the release notes against your configuration, confirm which hosts or images run JDK 25 since 26.6.0 requires it, and approve the change window. Operators must also schedule backups, control validator restarts and sign off on staging results. For a network with several organizations, each operator needs a named contact who can take a node down and bring it back. Ask the provider to list these roles in the scope so that gaps are visible before work starts.
Can our team upgrade Besu to 26.x without outside help?
Yes, a team with Linux or container operations skills and access to a staging network can do it in-house, provided it treats the work as a controlled change. The steps that most often cause trouble are the one-way Bonsai database upgrade in 26.10.0, which auto-upgrades on first start and cannot be opened by older Besu versions, and any custom plugin that depends on removed or changed APIs. Outside help is most useful for independent staging tests, plugin compatibility checks and a documented rollback path. Decide early which of these you will do yourselves.
How do we avoid stalling the network during rolling validator restarts?
Restart validators one at a time and keep enough of them online to preserve QBFT consensus, which requires two-thirds of validators to remain available. Before each restart, confirm that the node is peered with the others, that the previous node has rejoined and is producing or importing blocks, and that metrics show normal block height. Keep the upgrade order and rollback steps written down, and stop the sequence if any node fails to rejoin. Metrics can be exposed with the --metrics-enabled option on the default port 9545, which gives your monitoring a clear signal during each step.
Can a Clique network stay on an older Besu release?
A Clique network should not move to 26.4.0 or later. Besu 26.4.0 (April 22, 2026) removed Clique consensus, and according to the release notes, Besu can no longer start or produce blocks on pure Clique networks. A network still running Clique on an older release must plan a consensus migration to QBFT or IBFT 2.0 before it can run current versions, and that migration needs its own design, testing and coordination across operators. Confirm your current release, check the chain's consensus configuration, and ask any provider to show how the migration would be sequenced.
What to ask a partner for in a written upgrade scope
A fixed-scope upgrade quote for permissioned Besu nodes should name each piece of work, so you can compare proposals on the same basis. Ask for a release review that covers every release between your current version and the target 26.x release, with the JDK 25 requirement and the Clique removal in 26.4.0 called out as separate items. The review should state which of your nodes run configuration or plugins affected by those changes. Ask for a JDK 25 runtime rebuild as its own line: the rebuilt host or container images, the JVM options carried over, and the plugin builds retested against the new runtime. Confirm with the partner whether the rebuild covers only Besu nodes or also the monitoring agents and deployment tooling on the same hosts.
The scope should also list a backup and restore test and a staging environment as deliverables, not assumptions. Because the Bonsai database upgrades on first start and older versions cannot open it, ask for a documented backup of each node's data directory, a timed restore onto a separate host, and proof that the restored node syncs. Ask who provides the staging network, how closely it matches production validator count and peering, and whether the staging test includes a rolling validator restart. The rolling validator plan should set the upgrade order, the number of validators offline at any moment, and the peering checks before and after each node. Ask for named verification checks (block production, peer counts, JSON-RPC authentication still working, metrics reaching Prometheus) and a written rollback procedure that says which backup is restored and who makes the call.
Finally, request handover records: updated runbooks, the change record for each node, test results, and the configuration files as they stand after the upgrade. These documents are what your operators and auditors will read later. DeployOpen does not publish a price list. A quote follows from the written scope, so the more precisely these items are defined, the more precisely the quote reflects the work. Ask the partner to state what is excluded, what you must provide (access, change windows, staff time), and whether any item recurs after go-live, such as a retainer for later 26.x releases.
How DeployOpen works on this
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside the client's own infrastructure, so a Besu 26.x upgrade is scoped against your nodes, your validators and your backup tooling. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Inventory every node, validator and client version, including JDK, container images and deployment method, before naming a target 26.x release.
- Map each release note between your current version and the target against your configuration, plugins and RPC API usage.
- Agree in writing whether Bonsai database migration, Clique removal or privacy feature removal is in scope, with each deliverable listed.
How we build
- Prepare a staging network that mirrors production topology, validator count and peering so the upgrade is rehearsed before any live node moves.
- Verify the JDK 25 runtime, JVM options and any custom plugin builds on the staging hosts and images used for production.
- Write the rolling validator restart sequence, the pre-upgrade backup procedure and the rollback steps, then test them on staging before go-live.
How we hand over
- Deliver the runbook, change records, backup verification results and staging test evidence in a form your change board and auditors can review.
- Walk operators through the restart order, health checks for peering and block production, and the criteria for stopping and rolling back.
- Document the final configuration, versions and plugin pins so the next calendar release starts from a known, recorded baseline.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, so the next 26.x release can follow the same tested process.
- Retainer scope, response expectations and service levels are set in writing, so ask for them as part of the quote.
- Ask DeployOpen to confirm which upgrade services recur and which were one-time before signing any agreement.
