Troubleshooting - Whitechain

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.

cp .env.testnet.example .env

See Node configuration for the full list of variables.

Missing `artifacts/<network>/genesis.json`

Artifacts are missing or the folder name does not match WHITECHAIN_NETWORK. Place genesis.json and rollup.json under artifacts/<network>/. The folder name must match the WHITECHAIN_NETWORK value in .env.

public-rpc-node/artifacts/testnet/genesis.json
public-rpc-node/artifacts/testnet/rollup.json

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, restore a snapshot or 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 a snapshot but the node resyncs from genesis

Check these three things:

Confirm the data landed in the right place: data/<profile>/op-reth/db and data/<profile>/op-reth/static_files must exist.
Confirm the snapshot matches WHITECHAIN_NETWORK and the profile you start.
Make sure the node was stopped during extraction.

See Restore from a snapshot for the full procedure.

Sync is slow

Common causes, in order of likelihood:

No snapshot restored on a long-running full-node or archive-node, so the node re-executes from genesis. Restore one, or use full-snap-node.
L1 endpoint is rate-limited or slow. Switch to a faster L1 RPC and Beacon, or run your own L1 node.
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.

echo "behind by $((($(date +%s) - $( \
  curl -s -X POST http://127.0.0.1:9545 \
    -H 'Content-Type: application/json' \
    --data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' \
  | jq -r .result.unsafe_l2.timestamp)) / 60)) minutes"

​Missing .env

​Missing artifacts/<network>/genesis.json

​Compose refuses to start, asks for PUBLIC_IP

​Compose refuses to start, asks for WHITECHAIN_PUBLIC_RPC

​WHITECHAIN_RETH_TRUSTED_PEERS missing (full-snap-node only)

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

​full-snap-node is not snap-syncing

​Restored a snapshot but the node resyncs from genesis

​Sync is slow

​optimism_syncStatus shows unsafe_l2.number = 0

​nonce has already been used when deploying

​Related