Troubleshoot a node

Start with the symptom, collect a small amount of evidence and correct the identified cause. This guide is for the released non-validator full node. Validator signing, jailing and key recovery are separate procedures. Use Monitor a node for status and fixed-height comparisons. Local RPC checks use the published ports. The systemctl, journal and /var/lib/tavchain-fullnode examples below apply only to the earlier systemd installation. For Docker, inspect the container and logs using the Docker guide. For a native bundle, inspect output in its running terminal and use the same home selected by its launcher. Neither installation creates tavchain-fullnode.service.

Service will not start

sudo systemctl status tavchain-fullnode.service --no-pager
sudo systemctl show tavchain-fullnode.service --property=Result,ExecMainCode,ExecMainStatus,NRestarts
sudo journalctl -u tavchain-fullnode.service -n 100 --no-pager

Read the first relevant startup error, rather than treating the final process exit as the cause.

Symptom	Check next
Binary missing or not executable	Verify the unit’s versioned `ExecStart` path and the release checksum/signature checks in the installation guide
Permission denied	Verify ownership of the chosen home and access for the service account; do not make private directories or keys world-readable
Address already in use	Find the process using the expected port; do not start a second node against the same home
Wrong genesis/network or genesis hash error	Compare the installed release and genesis with the authenticated network files; preserve the existing home for investigation
Database or I/O error	Check storage availability and the filesystem; preserve state and obtain help before attempting repair

The published service runs as tavchain-fullnode and writes only its own home. Running it as root or loosening all permissions is not a diagnosis.

Local RPC refuses the connection

Confirm that the node is running and inspect the loopback listeners:

sudo ss -ltnp '( sport = :29656 or sport = :29657 or sport = :29645 or sport = :29646 )'

The packaged profile uses native RPC 127.0.0.1:29657 and EVM HTTP 127.0.0.1:29645. A request to another host, a production-validator port or the wrong interface will not test this node. A container’s 127.0.0.1 refers to that container, not its host. A timeout is different from a refusal: inspect the endpoint, logs and host load before assuming the chain has stopped. Keep the listeners on loopback; opening a firewall or binding RPC to every interface is not needed to diagnose local access.

No peers or stalled sync

Check /net_info and /status using the monitoring commands. Inspect the peer errors in the journal, then compare the selected release’s persistent peers with Network files and ports. The accepted full-node profile connects outbound to the three published cloud peer endpoints. It needs no incoming firewall opening for this workflow. Verify outbound connectivity to their advertised host and ports. Those three peers share one cloud host; they do not provide three independent hosting failure domains. Check accurate host time and available disk/inodes. During initial genesis sync, height should advance toward the network tip; it need not be caught up immediately. If the public reference progresses while your node remains at one height, investigate local peers, logs and host resources. If both stop, reference failure or a network incident is also possible; do not infer the cause from one endpoint.

Process active but node behind

active (running) confirms that the process exists, not that it is ready for applications. Check height over time, peer connectivity and catching_up, then compare a fixed common block with the public reference. A matching block far behind the tip proves agreement only at that old height. A different hash at the same height needs investigation. Keep the home intact; do not replace genesis or delete the database to silence a mismatch.

Repeated automatic restarts

The published unit retries unexpected failures after five seconds. Five starts within 120 seconds trigger systemd’s crash-loop protection. Find and fix the underlying error before clearing the failed state using the service lifecycle commands. Do not increase retry limits to hide the error. An explicit systemctl stop does not request an automatic restart. If graceful stop remains pending, inspect the journal, process and storage; do not launch another process on that home or force-kill it as a routine fix.

Disk or inodes running low

sudo df -h /var/lib/tavchain-fullnode
sudo df -i /var/lib/tavchain-fullnode

Check the filesystem holding your actual node home. Full history grows over time. Plan additional storage or a reviewed maintenance procedure before exhausting it. This guide does not prescribe deletion of block data, recovery logs, signer state or key files, and does not provide a pruning/reset/snapshot-replacement procedure.

RPC errors and pending transactions

An HTTP 200 response may contain a JSON-RPC error. Confirm EVM chain ID 771002, use the EVM HTTP endpoint for eth_* requests, and read the returned code/message. The public RPC can return HTTP 429 under load; slow down and retry read requests later. If a submitted transaction’s result is unclear, look up its existing hash in the explorer or RPC before submitting anything again. A receipt with status 0x0 means execution failed; inspect that transaction rather than assuming another submission will fix it. Do not give anyone a wallet password, seed phrase or private key to diagnose an RPC problem.

Maintenance and upgrade recovery

Use Upgrades and recovery for same-version restart and catch-up checks. Software changes need the target release’s compatibility and migration instructions; an older binary may not be able to read a database changed by a newer release.

Get help with safe diagnostics

Contact support@safeney.com with the client version, operating system, approximate UTC time, symptom, relevant error lines, height/peer count and any public transaction hash. Explain which steps you already checked. Review and redact diagnostics before sharing: logs and configuration can include private addresses, credentials or other sensitive information. Never send an entire node home, keyring, consensus key, P2P private key, signer state, private environment file or wallet secret. Support is best effort, with no guaranteed response time. Use release-specific instructions for upgrades or state repair. Validator recovery differs from full-node troubleshooting; do not copy signing keys or apply unjailing commands to a non-validator node.

Start here

Installation

Maintenance

Reference