Why rollback planning for Besu 26.10 starts with a backup
If your team runs a permissioned Besu network and plans to move a node to 26.10.0, rollback depends on a backup taken before the first start on the new version. The Bonsai database upgrades automatically the first time 26.10.0 starts, and older Besu versions cannot open the upgraded database, so reinstalling the previous release is not a recovery path on its own. Treat the pre-upgrade backup as the only rollback mechanism you can rely on.
The supported path runs through the earlier 26.x calendar releases. Besu ships roughly monthly, and the release list shows 26.9.0 on September 25, 2026 and 26.10.0 on October 16, 2026. Confirm with the Besu releases page which version each node in your network currently runs, because a node that jumps across several releases at once is harder to test and harder to roll back. Ask each operator to record their starting version, the target version and the date of the backup before any node is touched.
Make the backup a gated step, not a hopeful one. Confirm that the backup is complete, that you can restore it onto a separate host, and that the restored node starts and syncs before you upgrade production. Confirm whether the Besu revert-code-format subcommand fits your rollback plan, and check the release notes for how it behaves against a database in its upgraded state. Your change record should name who may approve a rollback, who performs the restore, and how long validators can stay offline during recovery.
What changes in 26.10.0 and what each change means for operators
This table lists each change in Besu 26.10.0 that affects stored data and rollback, with the impact on operators and the action to take before upgrading. Read it as a checklist: every row with a one-way effect needs a verified backup before the first start on 26.10.0.
| Change | Impact | Action needed |
|---|---|---|
| Bonsai database auto-upgrade on first start | The database upgrades automatically when a 26.10.0 node starts, with no separate migration step. | Take and verify a backup of each node's data directory before the first start. |
| Bonsai database version 4 and archive version 3 | Once upgraded, the database uses the new storage versions, which older Besu releases cannot read. | Confirm your rollback path does not depend on any Besu release earlier than 26.10.0 opening this data. |
| Jump destination analysis stored next to code | Code storage now holds jump destination analysis alongside bytecode, which changes what the stored data contains. | Plan for database size and disk I/O during and after the upgrade, and confirm headroom on each host. |
| One-way opening constraint | Restoring the old binary onto an upgraded database fails or risks corruption, so a downgrade is not a simple restart. | Restore from the pre-upgrade backup if you must return to an earlier version, and record which copy each node runs. |
| revert-code-format subcommand | Besu 26.10.0 adds a storage subcommand related to this change, which can convert code storage back to the earlier format. | Test the subcommand on a copy of a node's data in staging and confirm its behavior with the release notes before relying on it. |
| version-compatibility-protection setting | Guards against restarting a node with an earlier Besu version that might corrupt the database. | Set it to true on every node and confirm it is in the configuration your deployment tooling renders. |
How the one-way Bonsai upgrade removes the simple downgrade path
Reverting the Besu binary alone will not restore service once the Bonsai database has been upgraded. Besu 26.10.0 upgrades Bonsai databases automatically on first start, storing jump destination analysis next to code (Bonsai database version 4, archive version 3). Older Besu versions cannot open the upgraded database, so a node that starts on 26.10.0 and then fails cannot simply be pointed back at the previous release with its existing data directory. The backup must therefore be taken while the node is still running the prior version, and it must be a copy the team has tested to restore. Set --version-compatibility-protection to true as a guard against restarting a node on an earlier version that could corrupt the database. The Besu backup documentation describes the backup and restore approach.
The effect differs by node role, and the rollback plan should reflect that. A validator that falls behind after the upgrade may need a restore from backup to rejoin, which affects quorum planning during a rolling change. Archive nodes hold the full historical state, so their database is the largest to back up and restore, and the time needed for that work should be measured in your environment rather than assumed. RPC nodes serving applications may be easier to replace from a snapshot or resync, but that depends on how your topology is built. Confirm which nodes are validators, archive nodes and RPC nodes, which hold the only copy of a given history, and how each one would be restored in your own infrastructure.
Treat the revert-code-format subcommand as a recovery tool to test, not as a standard step in the upgrade. Its exact behavior and when it applies should be confirmed against the 26.10.0 release notes and tested on a copy of the database before any production node relies on it. Record which backup belongs to which node and version so that a restore never reapplies data to the wrong release.
What to prepare before touching the database
Rollback after a Bonsai upgrade is only as good as what you prepared before the first start on 26.10.0. The six items below are the decisions and records that make a backup usable, a staging rehearsal meaningful, and a rollback call fast when a node misbehaves.
Verified backup taken before upgrade
Take a backup of each node's data directory while the node is stopped, following the Besu backup and restore documentation, then confirm you can restore it on a scratch host. Because 26.10.0 rewrites the Bonsai database on first start and older versions cannot open it, this backup is the only rollback path. Check that the restore reaches a running node, not just that files were copied.
Inventory of node roles and data directories
List every node with its role (validator, boot node, RPC, archive), its host, its data path and its Besu version. Rollback is per node, so you need to know which databases were converted and which were not. Record the Bonsai and archive storage locations, since a backup that misses one directory cannot restore a working node.
Staging copy of production data
Restore a recent production backup into a staging network and run the 26.10.0 upgrade there first. Time the first start, confirm the node syncs and serves JSON-RPC, and test the revert-code-format subcommand on a copy. Staging proves the procedure, but only if its data and configuration match production.
Pinned plugin and JDK versions
Confirm the JDK 25 runtime your hosts and images use, since Besu 26.6.0 requires it, and pin every plugin, including any HSM plugin, to a version tested against 26.10.0. Keep the previous Besu image and its JDK available so a rollback does not depend on rebuilding old artifacts from memory.
Monitoring and change records
Set Prometheus metrics and alerts for peer count, block height and sync status on each node before the change window opens, so you can compare behavior before and after. Record the backup checksum, timestamps, versions and each step in the change record. Auditors and internal reviewers will ask for this evidence.
Named rollback decision owner
Name one person who decides whether to roll back a node, with a written threshold such as failure to sync or failure to serve RPC within a window you agree in advance. Include who restores data, who communicates with other operators and who approves the decision. Without a named owner, teams often hesitate while validators are offline.
How to protect against accidental downgrades
Besu includes a setting that checks the database version before a node starts. According to the Besu backup documentation, setting --version-compatibility-protection to true guards against restarting with an earlier Besu version that might corrupt the database. This matters for the Bonsai upgrade in 26.10.0 because a node that starts an older binary against an upgraded database is exactly the failure the guard is meant to catch. The guard is a runtime check on the node you start, so it only helps where the flag is set on every node before the upgrade begins.
- Set the flag in the node configuration: Add
--version-compatibility-protection=trueto the startup configuration on every node, including validators, RPC nodes and any archive nodes. - Set it before the upgrade, not after: A node that has already been downgraded and started may have been affected before anyone noticed, so the flag should be in place from the first 26.10.0 start.
- Keep it through every restart path: Confirm the option survives service files, Helm values, environment overrides and any wrapper scripts that build the command line.
- Test the refusal: In a staging network, start an older binary against a 26.10.0 database and confirm the node refuses to run, so you know the check works in your setup.
- Do not treat it as a rollback plan: The guard prevents one kind of restart. It does not restore the database to its earlier state.
Check that the flag appears in the effective runtime configuration of each node, not only in the source file.
Most accidental downgrades happen in deployment, not on a server operators are watching. A pinned image tag that is rolled back by a pipeline, a cached older image on one host, or a Helm chart reverted during an unrelated change can start an older Besu version against an upgraded database. Pinning the exact release and blocking deployments that would move a node backwards removes that path. These controls are yours to design, and their details depend on the tooling your organization already runs.
- Pin exact versions: Reference the full 26.10.0 image tag or a digest, not
latestor a floating major tag. - Block version decreases in the pipeline: Add a check that compares the requested Besu version with the version recorded on each node and fails the deployment if it would go backwards.
- Control image promotion: Restrict which registries and tags can reach production nodes, so an older artifact cannot be redeployed by mistake.
- Gate rollbacks behind approval: Require a named change approval and a confirmed backup before any pipeline run that reverts a Besu image on a node with an upgraded database.
- Record the version on each node: Capture the running client version in your monitoring so drift is visible.
Confirm with your platform team which pipeline stages can redeploy a previous image without human review, since those are the stages the guard must cover.
The people running the upgrade decide whether the technical controls are used correctly. A runbook makes the sequence explicit: which backup must exist, who confirms it, which nodes move first, and what happens if a node fails to start. It also defines who may decide to restore a backup and who may decide to stop an upgrade. Without written steps, an operator under pressure may restart an older binary to restore service, which is the situation the other controls are designed to prevent.
- Confirm the backup first: Make the runbook require a verified backup taken before any 26.10.0 node starts, with the restore procedure from the Besu backup documentation tested beforehand.
- Define stop conditions: Specify what a failed start means, who is authorized to stop the rollout, and that nobody restarts an older binary on an upgraded database without that decision.
- Separate roles: Keep the person who approves a rollback distinct from the person who executes it, and log both.
- Rehearse the procedure: Run the backup, restore and refusal steps in staging with the people who will be on call.
- Keep a change record: Capture the backup identifier, the versions involved and the time of each node change, which regulators and auditors typically ask for.
Before go-live, check that every on-call engineer has access to the runbook and to the backup location outside the node.
How to sequence the upgrade with rollback points
The sequence turns a one-way database change into a set of checkpoints, so each step has a verified state to return to before the next node is touched. Each checkpoint names what must be true before work continues.
Confirm the current release and read the 26.10.0 notes
Record the Besu version and JDK every node runs today, then read the 26.10.0 release notes against your configuration. Confirm that the Bonsai database will auto-upgrade on first start and that older versions cannot open the upgraded database. Your team owns this review. It is done when the change record lists the current version, the target version, and the release note items that apply to your nodes. The rollback point at this stage is the unchanged production fleet, which needs no action.
Stage and test the upgrade on a copy
Restore a copy of one node's data into a staging environment that matches production's configuration, plugins and JDK. Start the copy on the 26.10.0 build and confirm it syncs, serves JSON-RPC calls, and produces or follows blocks as expected. Also run the revert-code-format subcommand on a separate copy to confirm your team can execute it. The check is a documented pass on the staging run. The rollback point is the staging copy itself, which can be discarded without affecting the network.
Take and verify the backup
Stop or quiesce the node following your backup procedure, then take a backup of its data directory using the method in the Besu backup and restore documentation. Store the copy outside the node's host so a failed upgrade cannot overwrite it. Verify the backup by restoring it to a separate location and confirming the node starts on the previous version. The output is a restorable backup with a recorded checksum and location. The rollback point is this backup, and it must exist before any production node is upgraded.
Enable version compatibility protection
Set the version compatibility protection option to true in the configuration of every node in scope, so that a restart with an earlier Besu version is blocked instead of risking database corruption. Confirm the setting is in the deployed configuration, not only in a template, by checking the effective configuration on each host. The check is a node that refuses to start on an older binary during a controlled test in staging. The rollback point is the protection itself, which stops accidental downgrades from becoming silent damage.
Upgrade one node at a time with health checks
Upgrade a single validator or node, then start it and watch the first start complete the database upgrade. Check the node's logs for errors, confirm its metrics endpoint responds, and confirm its JSON-RPC interface works with your authentication setup. Do not begin the next node until this one is healthy. The output is a node running 26.10.0 with a clean startup record. The rollback point is the node's verified backup, and the decision to restore it must be made before the node is considered stable.
Confirm peering and block production
After each restart, confirm the upgraded node has peers, that peers include the other validators, and that blocks are imported without rejection. Compare chain height across upgraded and not yet upgraded nodes. Keep enough validators on the prior version to preserve consensus throughout, and confirm the quorum requirement for your validator count before each restart. The check is stable peering and continued block production across the whole set. The rollback point is the current node, since a failed check stops the rollout while earlier nodes remain healthy.
Define when rollback is abandoned
Agree in writing, before the rollout starts, the conditions under which the team restores from backup, and the point after which rollback is no longer an option. Once upgraded nodes have produced blocks that others depend on, restoring older data may create divergence, so confirm with your consortium how that case is handled. Record the decision owner and the evidence required. The output is a signed rollback decision record. The final rollback point is this agreed threshold, after which the team fixes forward on 26.10.0.
What makes a Besu database rollback plan take longer
This table lists the factors that stretch a rollback plan for the Bonsai database upgrade in Besu 26.10.0, with the reason each one matters and how to shorten its effect. Read each row as a question to answer before the change window is booked. The main takeaway is that rollback time is set by restore mechanics and approvals, not by the upgrade command itself.
| Driver | Why it matters | How to reduce it |
|---|---|---|
| Data size and backup duration | Restoring from backup is the only rollback path once the Bonsai database has upgraded, so the backup must be complete before any node starts on 26.10.0. Larger databases take longer to copy and verify. | Measure backup and restore time on a copy of production data, and ask your team to confirm how long a full restore takes on your storage. |
| Number of nodes and their roles | Each validator, boot node and RPC node has its own database, and each one needs its own verified backup. Rolling back a mixed set of nodes is harder than rolling back one. | Keep an inventory of every node, its role and its data path, and sequence backups so validators stay online while others are captured. |
| Custom plugins that must match the release | Plugins built against an older Besu version may fail to load on 26.10.0, and a rollback must restore the matching older plugin build as well as the data. | Pin each plugin build to a tested Besu version, store it with the backup, and confirm the rollback image includes the same plugin artifacts. |
| JDK 25 requirement since 26.6.0 | Besu requires JDK 25 from 26.6.0 onward, so a rollback that returns to an older Besu version may also need an older runtime on the host or image. | Keep the previous Besu image and its JVM runtime together in the change record, and test the rollback image on a host built the same way as production. |
| Staging fidelity | A staging network with small or synthetic data can pass the upgrade and still hide restore timing, peering and plugin problems that appear on production volumes. | Restore a recent production backup into staging, run the upgrade and the revert path, and record the results against the production configuration. |
| Approval and change-record requirements | Your change board or regulator may require a named rollback owner, a tested restore procedure and evidence of a verified backup before approval, which can add time to the window. | Ask your approvers which evidence they expect, prepare the backup verification and restore test records in advance, and agree the go or no-go criteria before the window opens. |
| Version compatibility protection | The --version-compatibility-protection option guards against restarting with an earlier Besu version that might corrupt the database. Nodes without it set have less protection during a mistaken restart. | Ask your team to confirm the option is set to true on every node before the upgrade, and to document how it is enforced in your deployment tooling. |
Questions teams ask before planning a Besu 26.10 rollback
What drives the cost and effort of a Besu rollback plan, and can we do it in-house?
Yes, many teams can write and test a rollback plan with their own staff, provided they have people who know the node layout and the storage paths. The effort is driven by the number of nodes, how each node is deployed (bare metal, Docker or Kubernetes), how backups are taken and stored, and how many environments must be rehearsed before production. Costs are mostly internal staff time, plus storage for backups and any test infrastructure. If you bring in a partner, ask for a fixed scope in writing that lists the environments covered, the restore tests included, the documents delivered and who signs off. Confirm with your own team which parts of the work you can absorb.
How long does rollback planning take before the Besu 26.10 upgrade?
The duration depends on data size, the number of nodes, and how your environment is built, so there is no fixed figure to quote. Time is typically spent on inventorying nodes and data directories, measuring how long a full backup and restore take on a copy of production data, rehearsing the procedure in staging, and getting approvals. Large Bonsai databases take longer to copy and verify than small ones. Confirm the timing with your own team by running a restore test on a representative node first, then use the measured duration to set the change window.
What must our team supply for a Besu rollback plan?
Your team needs to provide access to the environments where Besu runs, a current node inventory, and named release owners who can approve changes. Useful inputs include the Besu version and launch flags for each node, the location of the data directory, the backup tooling and storage target, and the monitoring you use to confirm that nodes are healthy. Release owners should confirm the upgrade order and the go or no-go criteria. Without these inputs, any plan will rest on assumptions, so gather them before scoping begins.
Can revert-code-format undo the Besu 26.10 database upgrade?
Do not treat it as a rollback mechanism until you have tested it. The 26.10.0 release adds a besu storage revert-code-format subcommand related to the storage change that moves jump destination analysis next to code. Confirm in the release notes exactly what it reverts, which database versions it supports, and whether it fully restores the state an older Besu release needs. Then test it in staging on a copy of real data, including starting an older client afterward. Keep a verified backup taken before the upgrade regardless of the result.
Do protection flags like version compatibility protection replace a backup?
No. The --version-compatibility-protection option guards against restarting a node with an earlier Besu version that might corrupt the database, but it does not restore data or make an older version able to open an upgraded database. The Besu 26.10.0 release notes state that older versions cannot open an upgraded Bonsai database, so the only reliable way back is a backup taken before the upgrade. Use the flag to prevent accidental downgrades, and use backup and restore procedures from the Besu documentation to recover.
How do we stop an accidental downgrade of a Besu node?
Set --version-compatibility-protection to true on every node so that a restart with an earlier Besu version is blocked rather than risking database corruption. Pin the container image or package version in your deployment tooling, record the version in your change log, and restrict who can deploy. Confirm that the flag behaves as expected in staging by attempting a downgrade on a test node. Protection like this reduces accidental risk, but it is not a substitute for a tested backup.
Which backup and restore steps should the rollback plan document?
The plan should describe how to stop the node cleanly, take a copy of the data directory or use the backup method the Besu documentation describes, verify the copy, and store it outside the node. It should also record how to restore that copy onto the same version it came from and how to confirm the node syncs afterward. Include the expected runtime for each step, the owner of each step, and the criteria for declaring the rollback complete. Review the Besu backup and restore documentation and adapt it to your deployment.
What to confirm with the Besu release notes and your own environment
Before any node is upgraded, the team should confirm the facts that this plan depends on, starting with the exact 26.10.0 release notes. The supplied facts say the Bonsai database upgrades on first start and that older Besu versions cannot open the upgraded database, but the release notes are the source for the precise wording, any caveats added in later patch releases, and the storage version numbers involved. Read them against the release page at Besu releases on GitHub, and record which version you read and when. Confirm also whether the besu storage revert-code-format subcommand is described as a reversal of the storage change, or only as a tool for a narrower case. If the notes do not say what the subcommand can and cannot undo, treat it as unproven for your rollback plan.
Next, confirm the backup procedure in the Besu documentation against your own setup. Check that the backup you take can be restored onto the Besu version you plan to roll back to, that it covers the full node data directory your nodes use, and how long a restore takes on your storage. Confirm how --version-compatibility-protection behaves in your Besu version and whether you will set it to true on every node before the first start on 26.10.0. Ask your operations team who can authorize a restore and who holds the backup, since a backup nobody can reach during an incident does not support a rollback.
Finally, confirm your own topology and plugin versions. List every node, its role (validator, bootnode, RPC, archive or other), its current Besu version and its storage location, and identify which nodes will be upgraded first. Check whether any custom plugin, including an HSM plugin, is built against a Besu version that can run on the target release, because a plugin that fails to load can block a restart in the middle of a rollback. Confirm that your monitoring can show each node's version and sync state during the change, so that a node restarted on the wrong binary is noticed quickly.
How DeployOpen scopes and supports a Besu upgrade
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, so rollback planning for the Besu 26.10 database upgrade runs in your environment and under your change control. Engagements are fixed-scope, with the written scope agreed before work starts.
How we scope
- Inventory every Besu node, its version, its data volume and where its database is stored.
- Define which node types, validators and archive nodes are in the upgrade and in what order.
- Agree in writing the backup, restore and rollback deliverables before any node is touched.
How we build
- Set --version-compatibility-protection in the node configuration and verify it loads on every node.
- Rehearse a backup and restore of the Bonsai database on a staging copy of production data.
- Test the revert-code-format subcommand on a copy so the team knows its effect before a live window.
How we hand over
- Deliver a runbook covering backup steps, go and no-go checks, and the restore sequence per node.
- Provide a record of each staging test, including timings observed and the versions used.
- Walk your operators through the rollback decision tree so the on-call team can act without us.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer for later Besu releases.
- Retainer work can cover re-checking backup and restore procedures against each new calendar release.
- Confirm the support boundaries, response expectations and named contacts in the written agreement.
