Troubleshoot

Common failure modes when following the chain, and what they mean.

Docs / Run a node / Troubleshoot

Failure modes when following chain 2800, and what each one actually means.

The node stops at a specific height and never passes it

failed persisting block due to stateroot mismatch means your client computes a different state than the chain. The height tells you which rule you are missing.

Stops atMissing
9,189,161The AERE EVM milestone: the five post-quantum precompiles and the EIP-2935 write
10,141,734 or shortly afterThe base fee floor
An anchor heightAn anchor rule: activation, interval, minimum seals, scheme schedule or registry path

All three are node options, not genesis settings. See Configure.

The node will not start at all

A threshold guard refusing to arm. A node syncing from genesis starts into the genesis validator set of three, and the anchor guard refuses a minimum of three or six seals against a set of three. The published answer is the seal-count ceiling described in Sync.

A file it cannot read. Configuration that is loaded lazily fails at the moment of use rather than at startup, which turns a permissions mistake into a consensus event. If you run in a container, prove that every mounted file is readable as the user the process runs as, before you start it.

Zero peers

Discovery is UDP. A firewall that opens only TCP produces a node that starts, looks healthy, and never finds anyone. Open both, inbound and outbound, and confirm with net_peerCount.

A node that calls its static peer in its first second, while the other side is not yet listening, can fail a handful of times in a fraction of a second and not try again. When bringing up two nodes that must find each other, start the one being called first, with its RPC up, before the one that calls.

The node is up but far behind

Check memory before anything else. On this chain the constraint is the heap against the storage engine's off-heap cache, and the symptom of a heap that is too large is not an error, it is a process that spends its time collecting garbage. The table in Requirements is the fastest way to see whether your setting is in the band.

It disagrees with a public endpoint about a recent block

First check block 0. If the genesis hash differs, nothing else matters: you are on another chain.

If block 0 matches and a recent header differs, compare the headers field by field rather than reading the difference as a fork. Each QBFT node assembles its own final header, and the block hash does not cover the seals, so two honest nodes can legally store different extraData for the same block.

An anchor header is rejected

Read the height against the anchor grid. Anchor heights sit on H + k * 128 from block 17,225,968, which is not the same as height % 128 == 0. A client testing the wrong condition rejects valid blocks and accepts nothing at the right ones. See Anchor schedule.