Which sync mode should a node joining a private Besu network use?
An existing permissioned network needs a new validator, RPC node or read-only node, and the first decision is how that node catches up to the chain head. A sync mode controls how a node acquires the state it needs before it can validate new blocks. In a private network, the choice is usually between full sync from genesis, which replays every block and rebuilds state locally, and snap sync from peers, which downloads a recent state snapshot and then follows the chain. This section covers the decision and the conditions behind it. The flag names, peer requirements and database behavior belong to Besu's documentation and release notes, so confirm them against the exact version your network runs before you write any configuration.
Full sync from genesis is the simpler path when the chain is short, the history is small, and the team wants the joining node to verify every block itself from the first one. It needs no special support from peers and avoids depending on a snapshot being served correctly. The cost grows with chain length and transaction volume, so a network that has run for a long time, or that has heavy throughput, may find the catch-up slow and disk-intensive. Snap sync from peers is the faster path for a long-lived network, but it depends on the existing peers being configured to serve snapshots. Before you choose it, confirm that the peers you plan to use support snap serving on the Bonsai database, and that the joining node runs a compatible version. A joining validator should also be checked against its trust model, since it will take state from peers rather than verify history from genesis.
Treat the choice as a rehearsal item, not a late decision. Join a node to a test copy of the network using each mode you are considering, measure time to head and disk use, and record which flags and peer settings worked. Ask the network's operators whether their nodes serve snap sync, and whether any node in the network still uses the deprecated checkpoint mode, which the maintainers have moved away from. Write the chosen mode into your runbook with the Besu version, so that the next node added by a different team starts from the same procedure.
Comparing sync modes for a joining Besu node
This table compares how a new node obtains chain state under each sync mode, what existing peers must provide, and what the operator checks afterward. Use it to match a mode to validators or RPC nodes, then measure time and disk use on a rehearsal node before you commit to a join plan.
| Aspect | Full sync from genesis | Snap sync from Bonsai peers | Checkpoint mode and fast sync |
|---|---|---|---|
| How the node obtains state | Executes every block from genesis to build state locally. | Downloads a state snapshot from peers, then syncs the blocks that follow. | Checkpoint starts from a trusted block. Fast sync is deprecated and announced for sunsetting. |
| What existing peers must serve | Full block and receipt history from the genesis block onward. | Bonsai-format state and the snap sync protocol. Confirm the required peer settings in the Besu docs. | Blocks from the checkpoint onward. Fast sync peers must still serve its state data, so plan to remove it. |
| What the operator verifies afterward | Block height, head hash and peer count match the network. Compare against a known validator. | Same head checks, plus confirmation that the snapshot completed and the node follows the chain head. | Confirm the checkpoint block was agreed out of band by the consortium, then run the head checks. |
| Storage and upgrade behavior | Storage grows with full history. Confirm disk needs on a rehearsal node. | Bonsai auto-upgrades on first start, and older Besu versions cannot open it. Back up first. | Not a planning target. Migrate existing nodes to a supported mode and remove the setting. |
| Fit for validators | Suits validators that must hold full history from genesis, such as for audit. Expect a longer join. | Suits validators when all peers run Bonsai and the snapshot path is rehearsed and verified. | Avoid for new validators. Use only for a documented legacy node until migration. |
| Fit for RPC and read-only nodes | Fits RPC nodes that must serve full historical queries from their own storage. | Common choice for RPC nodes that must join quickly, provided the peers support it. | Avoid for new RPC nodes. Plan a move to a supported sync mode. |
| Dependence on peer configuration | Low. Any peer that holds the chain can supply blocks. | High. Requires Bonsai peers with the right settings, so check every peer before joining. | High for fast sync, which depends on peers that still serve its data. |
| What to measure on a rehearsal node | Elapsed sync time and disk growth from genesis to the current head. | Elapsed snapshot time, the time to reach head, and disk use after the Bonsai upgrade. | Time to trust the checkpoint and the time to catch up to head after it. |
What peers must serve for snap sync to work
Snap sync is a shared decision, not only a setting on the new node. A joining node can only snap sync from peers that hold Bonsai data and are configured to serve it, so the peers already in the network determine whether the new node can use snap sync at all. Before you choose a sync mode for a joining node, confirm with the Besu documentation for your exact release which peer-side options must be enabled, and agree that configuration with every operator who runs a node that the new node might connect to. If a peer runs a different database format or lacks the serving option, the joining node will not get the data it expects, and the failure may only appear after a long wait.
Check that a peer is serving snap data before the new node depends on it. Start a test node in a non-production environment, point it at the candidate peer, and confirm the sync progress and peer logs show snap data being served. Repeat the check against each peer you plan to list as a bootnode or static peer, since a peer that works today may be upgraded, reconfigured or resynced later. Record which peers passed the check and make the check part of the runbook for adding nodes, so the test is repeated whenever peer configuration changes.
Fast sync and checkpoint mode belong in the plan only as history. The Besu maintainers have placed fast sync on their sunset list, so a network design that depends on it will need rework during a future upgrade. Checkpoint mode is deprecated, so treat any older guide or configuration that mentions it as a reference to be replaced, not a supported path. Ask your Besu contacts or the release notes which options remain supported in the version you run, and document the decision so that a future operator does not copy an outdated setting from a legacy runbook.
Setup sequence for a joining node with sync checks
This sequence brings a new node into an existing private Besu network without guessing at versions, peers or data. Each step ends with a check, so the team knows the node can serve the chain before it is treated as production-ready.
Confirm the network's Besu version and database format
The team that owns the chain confirms which Besu release every existing peer runs and which database format each one uses. Check the release notes for the target version, including the JDK requirement, which the 26.6.0 notes list as JDK 25. Note that the Bonsai database upgrades automatically on first start in the 26.10.0 release, and older versions cannot open an upgraded database. Done when the version, JDK and database format are written into the change record and match across the peers you plan to sync from.
Inventory existing peers and their sync capability
The node operator lists the validators, RPC nodes and bootnodes the joining node will connect to, with each node's Besu version, database format and reachable P2P and RPC addresses. Confirm in the Besu documentation which settings let a peer serve snap sync data from Bonsai storage, and enable them on the peers that will serve the new node. Fast sync has been sunset, so do not plan around it. Done when every planned peer answers on its P2P port and runs a version that supports the chosen sync path.
Prepare the joining node configuration in Git
The node operator writes the configuration file, genesis file, permissions files and metrics settings in a Git repository, using the same genesis file as the network. Peer addresses come from the inventory in the previous step, and the sync mode is set to the option described in the private networks docs for the chosen path. The node private key file is not encrypted by Besu, so store it under your key management standard and keep it out of the repository. Done when a second reviewer approves the change and the genesis file checksum matches the one peers run.
Back up existing node data before any change
Before the node starts on a new version or reuses an existing data directory, stop the process cleanly and copy its data directory to storage outside the node. This matters because the Bonsai database upgrades on first start, and an older Besu version cannot open the upgraded database, so a rollback depends on this copy. Restore the copy to a scratch location to confirm it is readable. If the joining node is brand new with an empty data directory, record that no backup is needed. Done when the backup location is in the change record and the restore test succeeds.
Start the node in the chosen sync mode
The node operator starts the joining node with the configuration from Git and watches the startup logs for peer connections and sync progress. Confirm the log shows the Besu version you expect, that the node connects to the planned peers, and that it begins downloading state. Keep the JSON-RPC interface restricted to administrators during this stage. Done when the logs show the expected version, at least one peer is serving sync data, and repeated connection failures have stopped.
Confirm the node reaches the chain head
Compare the joining node's current block height with the height reported by a trusted validator or RPC node. Run the eth_blockNumber call against both nodes and repeat the comparison as sync progresses. The join is not complete while the node trails the head, so hold application traffic until it catches up. Done when the two heights match within normal block production and the node imports new blocks as they are produced.
Verify the node stays connected and in sync
Once the node reaches the head, watch it through a set observation window that your team defines, tracking peer count, block import rate and any restarts. Prometheus metrics, enabled with the metrics option in the Besu documentation, provide the same signals as the logs and can feed dashboards your team already runs. Restart the node once in a controlled test to confirm it reconnects to peers. Done when the peer count stays stable through the restart and the node keeps pace with new blocks. Store the peer list and metric baseline in the change record for comparison with the next joining node.
Security and operating risks while a node syncs
A joining node is exposed from the moment it starts: it trusts peers for chain data, it needs a key and network path, and its database and endpoints change during catch-up. The cards below cover the risks to close before the node reaches the network, and the documentation page where each control is confirmed.
Stale or unauthorized peers
A joining node takes block and state data from whichever peers it connects to, so a peer that is out of date or not part of your network can feed it a misleading view of the chain. Confirm that the joining node only accepts connections to known participants by reviewing its node permissioning file, and that bootnodes and static peers are listed explicitly. Test this with a peer that is not on the allowlist before the node joins for real.
Permissioning that blocks the sync path
Node permissioning can stop the joining node from reaching the peers it needs to download history, so sync stalls with no obvious error. Check that the permissions configuration on every existing peer lists the new node's node ID, and that the new node lists the peers it will sync from. Treat a sync that does not advance as a permissioning question before you suspect the chain.
Unprotected node private key
The node private key file that identifies a joining node is not encrypted by Besu. Restrict file permissions on the key from the first start, keep it out of images and shared configuration repositories, and create a new key for each node rather than copying one. If your policy requires hardware-backed storage, confirm with the vendor whether a security module plugin is available for your Besu version before go-live.
Irreversible database upgrade on first start
The Bonsai database upgrades automatically the first time a newer Besu starts, and older binaries cannot open the upgraded database. A joining node that is started with a newer binary than the rest of the network, or that is restored into an older version, can become unusable. Take a backup of the data directory before any upgrade, and pin the binary version used for joining nodes to the version your network runs.
Sync progress visible from day one
A node that is catching up can look healthy while it lags far behind the chain head. Enable metrics from the first start so you can track current block height against peers, peer count and sync status. Add an alert for a node that stops advancing, since this is the earliest signal of a permissioning, peer or disk problem.
RPC exposure during catch-up
A node that is still syncing returns incomplete state, yet its JSON-RPC port may already be reachable by applications. Keep the RPC interface bound to a private network until the node is at the chain head, and require authentication before exposing it. Confirm the authentication method in the JSON-RPC docs, since Besu does not terminate HTTPS itself and needs a proxy or private network path for transport security.
Sync mode questions before you bring in a new node
How much effort does it take to bring a new node into a private Besu network?
The effort depends less on the act of starting a node than on the preparation around it. The main drivers are the sync mode you choose, the number of peers that can serve data, the size of the chain state, and how many node roles and organizations are involved. A full sync from genesis re-executes every block, so it takes the longest and puts the most load on peers. Snap sync from Bonsai peers is usually the faster path, but it only works when the existing network runs the right database layout and the peers have the required settings enabled. Ask your team or a partner to list each peer's configuration, the chain height, and the database format before estimating the join.
Can our own team bring a node into the network without outside help?
Yes, if your team already runs Besu nodes, has access to the existing peers, and can test the change outside production first. The work is mostly configuration and verification: enabling the right sync settings on peers, starting the new node, confirming it reaches the chain head, and checking that it reads from the expected peers. Teams with no Besu operating experience usually find the peer and permissioning checks harder than the sync itself. A partner is most useful when the join must happen on a live network with several organizations, when the rehearsal environment does not exist, or when internal staff are needed for other changes at the same time.
What do we need to provide from our side for a node join?
Plan for four things before the change window is set. First, network access: the new node must reach the peers it will sync from, and those peers must allow the connection under their own permissioning rules. Second, a rehearsal network where the same sync steps can run without touching production. Third, monitoring: Besu exposes metrics for Prometheus when --metrics-enabled is set, so the new node and its peers should be scraped before the join starts, which lets you see sync progress and peer counts. Fourth, a change window agreed with every organization that operates a peer, because peers may need configuration changes or restarts.
How does sync time depend on data size and peer capacity?
Sync time grows with the amount of chain history a node must process and with how quickly peers can answer requests. A full sync processes every block from genesis, so it grows with chain length. Snap sync copies state from peers rather than replaying every transaction, so its cost is more tied to state size and peer bandwidth. If several new nodes join at once, peers share the load, and under-provisioned peers slow every join. The Besu documentation and release notes do not give a fixed duration for a given chain, so measure it on your own network in a rehearsal and ask any partner to base the schedule on those measurements.
What recurs after the new node goes live?
The one-time cost is the join itself. After go-live, the node needs ongoing care: Besu releases roughly monthly, so the node must be upgraded on a planned path, and the Bonsai database upgrades automatically on first start. Older Besu versions cannot open an upgraded database, so every upgrade needs a backup taken first. Monitoring, log review, peer health checks, disk growth and key custody also recur. If you want a partner for this, ask for the support scope in writing, including how upgrades are rehearsed and who responds when a peer drops.
What should a written scope for a node join include?
A written scope should name the sync mode and the reason for choosing it, the peers that will serve the sync, and the Besu version on the new node and on each peer. It should list the peer settings to be changed, the rehearsal steps, the monitoring to be in place before the join, the acceptance checks (chain head reached, peer count, block import), the rollback plan with a backup taken before the upgrade, and the change window. It should also state who on each side approves changes to peers, what is out of scope, and who supports the node after go-live. Ask for a quote built from this scope rather than from a headline number.
Is checkpoint sync a safe option for a new private network node?
Checkpoint sync should not be used for a new node in a current private network. Besu documentation describes it as deprecated, so treat it as a legacy option that your team should verify before relying on it. Fast sync is also sunset, as the maintainers announced in their sunsetting notice. The supported path for most private networks is full sync for a small chain or snap sync from Bonsai peers when the peers are configured for it. Confirm the exact flags and deprecation status against the Besu version you will run, since the release notes list removals across recent versions.
Limits to confirm for sync modes in your network
Sync mode choice depends on facts about your own network that no general guide can settle. The cards below list the items to confirm before a joining node is built, and each one is checked against the vendor documentation or a rehearsal network.
Besu release and database format
Confirm which Besu release every existing node runs and which database format it uses. Snap sync from Bonsai peers depends on the peers using Bonsai, and the Besu 26.10.0 release notes state that the Bonsai database upgrades automatically on first start and that older versions cannot open an upgraded database. Check this against the upgrade plan before you choose a sync mode, and take a backup before any upgrade.
Snap data from existing peers
Confirm that the peers you plan to connect to are configured to serve snap data. A joining node can only sync from a peer that enables the snap protocol and holds the data it requests. Verify the peer configuration on each node you intend to use as a sync source, not only on the bootnodes, because a node that does not serve snap data cannot help a snap sync.
Checkpoint and fast sync status
Confirm how the checkpoint and fast sync modes apply to your Besu version. The maintainers have announced the sunsetting of fast sync, so a network that depends on it needs a documented alternative. Read the status for your release in the vendor documentation and do not copy sync settings from older guides or forum posts.
Expected sync time on your hardware
Measure sync time on hardware that matches the production node, not on a laptop or a shared test host. Sync duration depends on disk throughput, memory, network latency to peers and the size of the chain at the time you join. Run a rehearsal join on a copy of the network and record the elapsed time so the go-live plan reflects your own numbers.
Protocol and client compatibility
Confirm that the joining node runs a release that supports the consensus protocol on the network, and that its JDK matches the release requirement. Besu 26.6.0 requires JDK 25, and Besu 26.4.0 removed Clique consensus, so a node built for an older network may fail to start or produce blocks. Check the compatibility notes for both the joining node and the existing validators before you schedule the join.
Permissioning rules that delay peers
Confirm that the permissions configuration on every existing node allows the joining node to connect, and that the joining node's enode is listed where required. Node permissioning restricts connections to known participants, so a missing entry can block peer discovery and make a sync appear stalled even when the sync mode is correct. Update the allowlists on all peers first, then start the new node.
How DeployOpen works on this
DeployOpen plans and delivers the join of new nodes to your private Besu network inside your own infrastructure, starting from the sync mode each node needs and the settings your peers must already have. The work is agreed in writing before it starts, so your team knows which nodes are joining, how they are verified and what evidence you keep.
How we scope
- Inventory every node that will join, its role, and whether it is a validator, RPC node or read-only node.
- Confirm the Besu version running on existing peers and whether Bonsai is the database format in use.
- Record which peers will serve snap sync and which will be used for full sync from genesis.
- Agree in writing the fixed scope, deliverables and timelines, with ongoing support available as a retainer.
How we build
- Configure the sync mode, peer discovery and snap-serving settings on existing and joining nodes under version control.
- Test each join in a non-production copy of the network before any change reaches a live validator.
- Check that joined nodes reach the chain head and produce the same block hashes as peers.
- Confirm that no deprecated checkpoint or fast sync settings remain in any configuration file.
How we hand over
- Deliver a runbook for each join method, with the exact configuration keys and the verification steps used.
- Document the expected sync duration, disk growth and monitoring signals to watch during a join.
- Walk your operators through a rehearsed join so the procedure is repeatable without DeployOpen present.
- Provide the configuration, test records and change history in a form your auditors and reviewers can read.
How we support
- Support later joins, Besu upgrades and peer configuration changes under a retainer if your team wants it.
- Review sync behavior after each Besu release, since snap sync requirements can change between versions.
- Help your team confirm which Besu database format and snapshot sources are supported before each upgrade.
- Ask your Besu vendor or the project documentation to confirm any capability before we rely on it.
