> ## 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.

# Upgrades and recovery

> Maintain an existing full node, prepare for client upgrades and recover from interruptions.

Preserve your full node's existing home and use the maintenance procedure for its installation method. The commands below apply to the earlier non-validator [systemd installation](https://docs.tavchain.safeney.com/tavchain/operate/node-service.md). Validator signing and key recovery require a separate procedure.

## Identify your installation

| Installation | Routine lifecycle instructions |
| - | - |
| Prebuilt Docker image | Use the stop/start commands in [Run a node with Docker](https://docs.tavchain.safeney.com/tavchain/operate/node-docker.md) and retain its named volume. |
| Native bundle | Use the same launcher and home from [Run a native node](https://docs.tavchain.safeney.com/tavchain/operate/node-native.md#stop-and-restart). Do not initialize again. |
| Earlier Linux systemd installation | Follow the service commands on this page. Its binary and home paths do not apply to the native bundle. |

These are restart instructions, not permission to exchange clients or migrate databases. Downloading a newer package does not upgrade an existing node or establish database compatibility.

## Check your version

This systemd guide uses **1.8.1-tavchain.eval1**, for native network `tavchaintestnet_771002-1` and EVM chain ID `771002`. Other installation methods have separate client releases; see [Release status](https://docs.tavchain.safeney.com/tavchain/status.md) for current compatibility.

For the published service installation:

```bash theme={null}
/opt/tavchain-evm/releases/1.8.1-tavchain.eval1/bin/tavchaind version --long
sudo systemctl show tavchain-fullnode.service --property=ExecStart,ActiveState,SubState
```

The version command describes that binary. Check that the service's `ExecStart` selects the same path; an old running process does not change versions just because another binary has been downloaded.

## Choose the right action

| Situation | Action |
| - | - |
| Routine maintenance, same client and healthy storage | Stop gracefully, then start the same service and home |
| Unexpected process exit | Inspect the journal and allow the configured restart behavior to work |
| Host reboot or a longer interruption | Start the existing service if needed, then check peers and catch-up |
| A new Tavchain release is announced | Follow its exact version, compatibility and activation instructions |
| Database errors, wrong genesis or conflicting block hashes | Preserve the home and investigate before changing software or data |

A restart does not require initialization, a new genesis, a wallet or a faucet claim.

## Stop and resume safely

For planned maintenance:

```bash theme={null}
sudo systemctl stop tavchain-fullnode.service
sudo systemctl show tavchain-fullnode.service --property=ActiveState,SubState
```

Wait until the service is inactive before continuing maintenance. The service sends SIGTERM and waits for graceful shutdown. If stopping remains pending, inspect the journal and host storage; do not start a second process against the same home.

Resume the same installation:

```bash theme={null}
sudo systemctl start tavchain-fullnode.service
sudo systemctl status tavchain-fullnode.service --no-pager
sudo journalctl -u tavchain-fullnode.service -n 100 --no-pager
```

Use the [monitoring checks](https://docs.tavchain.safeney.com/tavchain/operate/monitoring.md#check-network-and-sync) to confirm the network identity, peers, advancing height and completed catch-up. Then [compare a fixed block](https://docs.tavchain.safeney.com/tavchain/operate/monitoring.md#compare-a-fixed-block) with the public reference. Process status alone is not readiness.

## Recover after an interruption

The service retains its node identity and database. After an unexpected exit, systemd retries after five seconds; repeated failures can trigger its start-rate limit. An explicit stop does not trigger automatic restart.

1. Inspect the service result and the first relevant journal error.
2. Check available disk space, inodes, host time and outbound peer connectivity using [Troubleshoot a node](https://docs.tavchain.safeney.com/tavchain/operate/troubleshooting.md).
3. Correct the identified cause while retaining the existing home.
4. Start the service and verify catch-up and block agreement.

Only after correcting a failure that triggered systemd's start-rate limit, clear the failed state and start again:

```bash theme={null}
sudo systemctl reset-failed tavchain-fullnode.service
sudo systemctl start tavchain-fullnode.service
```

After a reboot, an enabled unit should start through systemd. Check its actual state and readiness; see [boot startup](https://docs.tavchain.safeney.com/tavchain/operate/node-service.md#optional-start-after-boot) for configuration. If the database cannot reopen, preserve it and contact support rather than repeating restarts or running a reset.

## Prepare for a software upgrade

A routine restart and a protocol upgrade are different operations. A protocol upgrade may require a specific client at a specific block height; incompatible clients may stop following the network.

Before changing versions, read the Tavchain release notice and confirm:

* The exact target release and supported source version.
* Authenticated downloads, checksums and the required platform.
* Any activation height or time and when operators must switch.
* Configuration changes and compatibility with the existing database.
* Post-upgrade checks and a release-specific recovery procedure.

Verify downloads using the [release authentication procedure](https://docs.tavchain.safeney.com/tavchain/operate/run-full-node.md#download-and-verify-the-release) and the target release's own manifest. Stage the new binary separately from the running executable. Keep the existing home; change the service's binary path only as directed by that release.

Use Tavchain's release-specific instructions. Other networks' binaries and upgrade procedures are not interchangeable with Tavchain's network identity, genesis and application configuration. The published service starts the client directly; an automatic upgrade manager is not included.

A newer binary may migrate persistent data. Returning to the old executable is not necessarily a safe rollback after it has written to the database. Follow that release's recovery instructions instead of assuming a binary downgrade will work.

## State repair and help

Keep the node home intact during investigation. Do not delete block data, replace genesis, import an unrelated snapshot or copy another node's keys as a routine repair. Full-node state repair and validator signer recovery have different requirements.

For assistance, use [Report an issue](https://docs.tavchain.safeney.com/tavchain/contribute/reporting.md) or email [support@safeney.com](mailto:support@safeney.com). Share the client version, operating system, approximate UTC time, symptom and redacted error lines. Never send an entire node home, credentials, private keys or signer state.

Check [network availability](https://status.tavchain.safeney.com/) alongside local diagnostics. A hosted status page is useful context, not proof that your own full node is ready.


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