Skip to main content
Common issues and their fixes when running a Whitechain RPC node.

​
Missing .env

No .env file found. Copy from .env.testnet.example or .env.mainnet.example and fill the required values.
See Node configuration for the full list of variables.

​
Missing artifacts/<network>/genesis.json

The artifacts are not part of the node repository. Copy genesis.json and rollup.json for your network in from whitechain-bootstrap, verifying their SHA-256 against the hashes published there, and place them under artifacts/<network>/. The folder name must match the WHITECHAIN_NETWORK value in .env. See Network artifacts.

​
L2 chain ID mismatch, L2 genesis timestamp mismatch, or L1 chain ID mismatch

genesis.json and rollup.json in artifacts/<network>/ do not belong together, or the pair does not belong to the network selected by WHITECHAIN_NETWORK. Re-copy both files from the same network directory of whitechain-bootstrap and re-check their SHA-256. See Artifact validation.

​
jq not found

make check-env uses jq to cross-check the artifacts before the node starts. Install it (apt install jq or brew install jq) and run the target again.

​
Compose refuses to start, asks for PUBLIC_IP

PUBLIC_IP is not set in .env. Set it to the public IP the node advertises for P2P.

​
Compose refuses to start, asks for WHITECHAIN_PUBLIC_RPC

The transaction-forwarding target is not set. Set WHITECHAIN_PUBLIC_RPC to the public Whitechain RPC URL in .env.

​
WHITECHAIN_RETH_TRUSTED_PEERS missing (full-snap-node only)

The full-snap-node profile needs a trusted reth enode to snap-sync from. Set WHITECHAIN_RETH_TRUSTED_PEERS to enode://<pubkey>@<ip>:30303 in .env.

​
failed to insert unsafe payload ... node is syncing

Expected during the initial consensus-layer sync of a fresh full-node or archive-node database. op-node receives an unsafe head over gossip, but op-reth has not re-executed up to its parent yet, so the forkchoice update returns SYNCING. Meanwhile Advancing bq origin log lines show L1 derivation is still progressing. The messages stop once the node catches up. To avoid the long catch-up, use full-snap-node.

​
full-snap-node is not snap-syncing

  • Confirm WHITECHAIN_RETH_TRUSTED_PEERS is a reachable reth enode (enode://<pubkey>@<ip>:30303) and the peer is up.
  • Confirm outbound EL P2P (devp2p) to that peer is not blocked by a firewall.
  • Check that op-node logs show --syncmode=execution-layer is active and op-reth reports syncing against the trusted peer.

​
Restored your own backup but the node resyncs from genesis

Check these three things:
  1. Confirm the data landed in the right place: data/<profile>/op-reth/db and data/<profile>/op-reth/static_files must exist.
  2. Confirm the backup was taken from the same WHITECHAIN_NETWORK and the same profile you start.
  3. Make sure the node was stopped during extraction.
See Back up and restore the datadir for the full procedure.

​
Sync is slow

Common causes, in order of likelihood:
  1. A consensus-layer profile (full-node or archive-node) on a chain with history behind it re-executes every transaction from genesis. Use full-snap-node if you need a fast bootstrap.
  2. L1 endpoint is rate-limited or slow. Switch to a faster L1 RPC and Beacon, or run your own L1 node.
  3. Disk I/O is the bottleneck. Move data/ to NVMe storage.

​
optimism_syncStatus shows unsafe_l2.number = 0

The node has not yet inserted the first L2 block. Wait a minute. If it stays at 0:
  • Check op-node logs for Reset of Engine is completed and Inserted new L2 unsafe block. If absent, the engine is not connected. Confirm op-reth is healthy on its HTTP port.
  • Confirm the genesis block hash in op-node logs matches the one in rollup.json.

​
nonce has already been used when deploying

The node is not fully synced. Wait for the optimism_syncStatus lag to drop close to zero before submitting transactions.