> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavchain.safeney.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot a node

> Diagnose startup, peer, sync and RPC problems without resetting node state.

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](https://docs.tavchain.safeney.com/tavchain/operate/monitoring.md) for status and fixed-height comparisons. Local RPC checks use the [published ports](https://docs.tavchain.safeney.com/tavchain/operate/network-assets.md). The `systemctl`, journal and `/var/lib/tavchain-fullnode` examples below apply only to the [earlier systemd installation](https://docs.tavchain.safeney.com/tavchain/operate/node-service.md).

For Docker, inspect the container and logs using the [Docker guide](https://docs.tavchain.safeney.com/tavchain/operate/node-docker.md). For a native bundle, inspect output in its running terminal and use the same home selected by its [launcher](https://docs.tavchain.safeney.com/tavchain/operate/node-native.md). Neither installation creates `tavchain-fullnode.service`.

## Service will not start

```bash theme={null}
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:

```bash theme={null}
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](https://docs.tavchain.safeney.com/tavchain/operate/monitoring.md#check-network-and-sync). Inspect the peer errors in the journal, then compare the selected release's persistent peers with [Network files and ports](https://docs.tavchain.safeney.com/tavchain/operate/network-assets.md).

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](https://docs.tavchain.safeney.com/tavchain/operate/node-service.md#stop-and-restart).

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

```bash theme={null}
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](https://explorer.tavchain.safeney.com/) 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](https://docs.tavchain.safeney.com/tavchain/operate/upgrades-recovery.md) 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](mailto: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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.