Guide
Node troubleshooting
What the common tenraid start-up errors mean and how to fix them, and what to check when a node finds no peers or falls behind.
On this page
The node does not start
| Message | Fix |
|---|---|
testnet has no built-in genesis manifest … | Pass the network's manifest with --manifest. Mainnet and development have one built in |
--network … does not match the … manifest | The manifest decides the network. Drop --network or use the right manifest |
standard public swarm needs a peer to connect to … | A testnet has no built-in peers. Give a --peer, or set bootstrap_peers in node.json |
mainnet checks blocks on the full TenQ dataset … | Add --tenq-threads <N>, or --tenq-light if memory is short |
mainnet requires storage.disk_pressure in enforce mode | Add the disk pressure guard to node.json |
a production validator requires validator_overlay listeners | Add validator_overlay to node.json |
validator_overlay requires a configured validator key | Remove the section, or give the node its validator key |
a validator on mainnet must build the TenQ dataset | Validators cannot use --tenq-light |
validator.heartbeat requires a configured validator key | Add consensus_key_file and password_file to the validator section |
… do not override it with --validator-key-file | Remove --validator-key-file; the key belongs in node.json |
validator.heartbeat.validator_id must be 96 … | Copy the ID again from tenrai-wallet positions |
the heartbeat fee key must differ … | Export a separate fee key, see Run a validator |
validator key file has unsafe local access controls | See A private file is refused |
the configured validator is absent from finalized state | The registration is not final yet, or validator_id is wrong |
the configured validator consensus key does not match … | consensus_key_file holds another key than the registered one, for example after a rotation |
validators and automatic validator heartbeats cannot use pruned storage | Switch to full or archive and resync from genesis |
| Validator or heartbeat requires complete history | The database lacks old block bodies, for example after a snapshot start. Resync it from genesis |
--tenq-prefetch needs --tenq-threads | Prefetching only exists with the full dataset |
P2P options need a swarm | An option such as --max-inbound was given without --listen, --peer, --sync-peer or public_p2p |
The same messages name testnet or testnet100 on those networks.
A private file is refused
The node keeps its identity in files only their owner may read, and refuses to use them otherwise. The same applies to validator key, fee key and password files. This happens after copying files to another folder or machine.
Linux
chmod 600 ~/.tenrai/mainnet/network/host.key ~/.tenrai/mainnet/network/mldsa65.seedmacOS
chmod 600 ~/.tenrai/mainnet/network/host.key ~/.tenrai/mainnet/network/mldsa65.seedWindows
The message is private file inherits Windows access rules. Remove the inherited rules and leave full control to your own account only:
icacls "$env:LOCALAPPDATA\Tenrai\mainnet\network\mldsa65.seed" /inheritance:r /grant:r "${env:USERNAME}:F"No peers
- Check the address and port of
--peeror--sync-peer. A value with an identity in front must carry the identity of that node. - Open UDP and TCP port 28700 in the firewall and forward it on the router, or try
--upnp. - A peer on another chain or protocol version is dropped after the handshake. Compare the manifest with the peer's operator.
The node falls behind
| Cause | Fix |
|---|---|
--tenq-light on a machine with few CPU threads | Use --tenq-threads with the 2 GiB dataset |
| A slow disk | Move the data directory to an SSD |
GET /v1/node/sync shows behind_by and the peers the node compares itself with.
The API refuses requests
| Answer | Meaning |
|---|---|
403 to a web page | Its origin is not in browser_origins. Add it with --browser-origin |
429 rate_limited | The per-address limit of the rpc section; wait retry_after_millis |
503 unavailable | The node is busy with a cut, or the disk guard is active. Retry shortly; check the free space if it stays |
A reset command fails
reset-db, reset-peers and reset-identity need --yes, and the node must be stopped first. cannot delete …; is the node still running? means a running node still holds the files.
The miner waits
tenrai-miner, the stratum bridge and the pool get no work while their node is catching up or has no peer to confirm its height. A dip of up to 30 seconds keeps the work coming; after that they pause, log it once, remind once a minute and start again by themselves when the node hands out work. Wait for synced. On a private network, enable mine_when_not_synced in node.json or start the node with tenraid run --mine-when-not-synced.