Skip to main content

​
Node won’t start

The data directory was previously initialized with a different genesis file.Fix: either pick a fresh --datadir, or wipe the existing one:
rm -rf /var/lib/geth/geth/chaindata
geth --datadir /var/lib/geth init genesis.json
Another process is using the port (30303, 8545, or 8546).Fix: find it with lsof -i :8545 and stop it, or pick a different port via --port, --http.port, --ws.port.
Linux’s default ulimit -n is too low for a full node.Fix: raise it. In systemd: LimitNOFILE=65536. In a shell: ulimit -n 65536.

​
Sync issues

Quantum Chain mainnet uses dedicated bootnodes. If your node is firewalled, discovery cannot work.Fix: open inbound UDP+TCP 30303, or pass --bootnodes <enode> for a known peer.
Snap sync needs sustained disk write bandwidth. HDDs and slow SSDs throttle the chain.Fix: use NVMe storage. For full and archive nodes, allocate --cache 4096 or higher.
Your node is running an old binary that pre-dates quantumVerificationBlock.Fix: rebuild from a tagged release: git fetch --tags && git checkout <tag> && make geth.

​
Validator (Clique) issues

Possible causes:
  • The address isn’t in the sealer set. Check with clique.getSigners().
  • The account is locked. Pass --unlock and --password.
  • The node hasn’t synced. Sealers must be at the head before they can seal.
  • It is “out of turn” — wait until the in-turn slot.
A sealer must wait (N/2 + 1) blocks between blocks it signs. This is anti-malleability protection in Clique. The warning resolves itself.
Sealer changes are applied at the next epoch boundary (every 30 000 blocks on mainnet). Use clique.proposals to confirm your vote is recorded.

​
RPC issues

--http.corsdomain and --http.vhosts block the request.Fix: add your origin (--http.corsdomain "https://app.example.com") and host (--http.vhosts "rpc.example.com").
The RPC namespace is not enabled.Fix: include it in --http.api. For example, eth,net,web3,debug,trace.
Default --rpc.gascap is 50 000 000. Heavy eth_call queries can hit it.Fix: raise the cap, or split the call.

​
Transaction issues

A transaction with this nonce was already mined or replaced.Fix: fetch the next nonce with eth_getTransactionCount(addr, "pending").
To replace a pending transaction, the new one must have a fee at least 10% higher.Fix: raise the gas price (legacy) or maxFeePerGas (EIP-1559) by 10%+.
Either the gas price is below the network minimum or the nonce has a gap.Fix: check txpool_status. For nonce gaps, fill the missing nonce. For low fees, replace at a higher fee.
The post-quantum signature does not verify against the public key registered for the sender address.Fix: confirm the signing service is using the correct key for the wallet, and that you targeted chainId=20803.

​
Disk usage

du -sh /var/lib/geth/geth/chaindata
If the database is growing faster than expected on a full node, prune: 
systemctl stop geth
geth snapshot prune-state --datadir /var/lib/geth
systemctl start geth
Archive nodes cannot be pruned — that’s the design tradeoff.

​
Where to look

SourceWhat it tells you
journalctl -u geth -fLive logs
eth_syncingSync progress
txpool_status, txpool_contentMempool contents
clique_statusSealer health
:6060/metricsPrometheus metrics
admin_peersConnected peers

​
Where to go next