Besu Certified Professional common mistakes
Besu Certified Professional · Understand the traps and how to avoid them.
Treating the genesis file's chainId, networkId, and the bootnode enode as interchangeable settings, then editing one to try to fix a peer-connection or replay-protection problem.
Candidates memorize that 'chain ID matters' but never map which value is used for transaction signing/replay protection (chainId in genesis and the eth_chainId RPC response), which is used for peer network matching (networkId / p2p network id), and which is purely a discovery address (enode URL with its public key and host:port). They then change the wrong field and the symptom persists or a new one appears.
What to do instead
Write out the three values before touching config: chainId = EIP-155 signing domain returned by eth_chainId; networkId = P2P network identity that must match across peers; enode = bootnode identity (64-byte public key) plus discovery port. Verify with eth_chainId, net_version, and admin_peers, and change only the field that maps to the failing behaviour.
Deploying a private network by reusing a public-network genesis (or a genesis whose alloc/extraData does not match the chosen consensus) and expecting Besu to start and produce blocks.
Candidates learn genesis structure in isolation and do not connect it to the consensus engine: IBFT 2.0 and QBFT require a non-empty extraData carrying the validator set in a specific RLP layout and require the validator addresses to be funded in alloc; Clique uses a different extraData signature layout; PoW-style genesis will not produce blocks on a validator set with no miners. Besu rejects or stalls on mismatch.
What to do instead
Pick the consensus first, then build genesis to match: for IBFT 2.0/QBFT, encode validator addresses in extraData (vanity + validator list + seal fields), fund every validator in alloc, set the correct consensus config block, and confirm block 0 is produced and subsequent blocks are sealed before adding more nodes.
Assuming a node that is 'running' is healthy: checking only that the process is up and the container is not restarting, without verifying peer count, block height advancing, and validator/sealer status.
Operational questions describe a node that starts cleanly but is isolated or stuck. Candidates stop at systemctl status or docker ps and never look at eth_blockNumber over time, net_peerCount, or the consensus-specific status endpoints, so they miss the actual failure (no peers, no quorum, validator not in the validator set).
What to do instead
Use a health checklist: sample eth_blockNumber twice with a gap and confirm it increases; check net_peerCount and admin_peers for inbound/outbound; for IBFT 2.0/QBFT confirm the node is in the validator set and that the validator count meets the fault-tolerance threshold (e.g. 3f+1); check logs for round-change and import errors.
Diagnosing 'transaction not mined' by only raising the gas price, without checking nonce ordering, the pending pool, and whether the transaction was accepted at all.
Candidates conflate the public-network mempool mental model with a permissioned network where a stuck lower nonce blocks all later transactions from the same account, or where the sender lacks funds for gas in the genesis alloc. They keep resubmitting with higher fees while the real blocker is a nonce gap or an unfunded account.
What to do instead
Trace in order: eth_getTransactionByHash (is it in the pool?), eth_getTransactionCount with 'pending' vs 'latest' (nonce gap?), eth_getBalance (gas funds?), then txpool inspection and node logs for rejection reasons. Fix the lowest blocking nonce first, then resubmit subsequent transactions.
Enabling privacy or permissioning features by flipping a flag in the config without provisioning the required external components (privacy enclave/private transaction manager, or the permissioning contract/allowlist files) and without restarting cleanly.
Candidates treat privacy and permissioning as Besu-only toggles. In practice privacy requires a cooperating private transaction manager and matching configuration on every participating node, and onchain permissioning requires a deployed permissioning contract plus node allowlists; file-based permissioning requires correct file paths and reload behaviour. Half-configured setups fail silently or reject all peers/transactions.
What to do instead
Before enabling, list dependencies: for privacy, the private transaction manager endpoint/keypair and identical privacy group configuration on participants; for permissioning, either the deployed permissioning contracts with correct addresses or the node/account allowlist files with correct paths and permissions. Then verify with a known-allowed and known-denied peer/account test.
Confusing the JSON-RPC namespaces and enabling only the default set, then wondering why admin, debug, or miner/consensus calls fail or why a method is 'not found'.
Candidates use RPC methods from memory without knowing which API namespace each belongs to (eth, net, web3, admin, debug, txpool, miner, perm, priv) and that Besu exposes namespaces via --rpc-http-api / --rpc-ws-api. A disabled namespace returns a method-not-found style error that looks like a bug rather than a config choice.
What to do instead
Map each method to its namespace and enable exactly the needed namespaces explicitly (e.g. --rpc-http-api=ETH,NET,WEB3,ADMIN,TXPOOL). Keep host/port and CORS/host allowlists consistent, and restrict exposed namespaces in production rather than enabling all.
Assuming a node upgrade or network migration is just swapping the binary/container image, without planning for consensus compatibility, database format changes, or coordinated validator restarts.
Candidates underestimate that Besu upgrades can change on-disk database formats, supported config keys, or consensus behaviour, and that restarting validators one at a time matters for liveness. They also forget that a network migration (new genesis/chain) needs fresh data directories rather than reusing old chain data.
What to do instead
Read release notes for breaking changes and DB migration steps, back up data and config, upgrade non-validators first, then validators one at a time while confirming block production continues; for a new network, use a new data directory and genesis and do not point the node at old chain data.
Configuring TLS and key material by generating ad hoc keystores/certificates and pointing at them without matching the node key, the TLS keystore, and the truststore/CA chain.
Candidates know 'use TLS' but not that Besu uses a separate node key (for P2P identity/enode), a TLS keystore for the RPC/communication layer, and a truststore for the peer/client CA. Mismatched passwords, wrong alias, or a missing CA in the truststore yields handshake failures that look like network faults.
What to do instead
Separate the three artifacts explicitly: node keypair (enode identity), TLS keystore (server identity with correct alias and password), and truststore containing the issuing CA(s). Verify with a client handshake test and check logs for certificate/trust errors before scaling out.
Writing and deploying a contract without accounting for chain-specific gas/opcode settings and the private/permissioned execution context, then treating a failed deployment as a compiler or Solidity problem.
Candidates debug at the source-code level while the failure is environmental: gas limits, the EVM/solidity target compatibility with the network's configured fork, contract size limits, or privacy-group execution where the contract must be deployed within the private group and its state is not visible on the public chain.
What to do instead
Check the deployment transaction receipt and revert reason first, confirm the network's fork/EVM configuration supports the compiler target, verify gas limit and contract size, and for privacy deploy and call within the correct privacy group so all participants share the same private state.
Relying on default ports, default bind addresses, and open RPC interfaces when reasoning about connectivity and security, instead of explicitly verifying what is listening and who can reach it.
Candidates assume defaults (RPC on localhost, P2P on 30303) hold in every deployment, but container networking, host bind addresses, and firewall rules change reachability. They also leave RPC exposed, which is both a connectivity confusion and a security issue.
What to do instead
Verify actual listeners (ss/netstat or container port mapping), bind RPC to loopback or a trusted interface, expose only the P2P port externally, and confirm reachability from a second host. Treat any RPC exposure as a deliberate, authenticated decision.