> For the complete documentation index, see [llms.txt](https://service.block-pro.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://service.block-pro.net/testnet/celestia/light-node/upgrade.md).

# Upgrade

Update your Celestia light node while keeping its existing store.

**Mocha testnet** · Chain ID `mocha-5`

Target release: [v0.34.3-mocha](https://github.com/celestiaorg/celestia-node/releases/tag/v0.34.3-mocha). Check [Versions](/testnet/celestia/versions.md) and the release notes before each upgrade.

This procedure follows the native systemd installation in [Light Node](/testnet/celestia/light-node.md). Run commands as the service's Linux user. Keep the same node type, network, keys and data store.

## 1. Check the running installation

Inspect the service user, binary path, network and any custom store flag. If your unit has a different name, use it throughout.

```bash
sudo systemctl cat celestia-light
```

Print the currently installed version. The path must match ExecStart; adapt it if your installation differs.

```bash
"$HOME/go/bin/celestia" version
```

Set the existing store path from your service configuration or startup logs. Replace this placeholder before continuing.

```bash
NODE_STORE="/absolute/path/to/your/existing/light-store"
```

Confirm that this is an initialized store. Stop if the check fails.

```bash
test -f "$NODE_STORE/config.toml"
```

Check Go. The selected release requires Go 1.26.8 or later; see Server Setup if you need to update it.

```bash
go version
```

## 2. Build the selected release

Build before stopping the node. This does not replace its running binary.

Choose the network-specific release.

```bash
NODE_VERSION="v0.34.3-mocha"
```

Create a fresh working directory.

```bash
UPGRADE_DIR="$(mktemp -d "$HOME/celestia-node-upgrade.XXXXXX")"
```

Download the source for the selected tag.

```bash
git clone --branch "$NODE_VERSION" --depth 1 https://github.com/celestiaorg/celestia-node.git "$UPGRADE_DIR/source"
```

Enter the source directory.

```bash
cd "$UPGRADE_DIR/source"
```

Compile the node binary.

```bash
make build
```

Compile the matching key utility.

```bash
make cel-key
```

## 3. Stop and back up

If multiple services use the same binary, coordinate their maintenance before replacing it. For a release that changes the datastore, take a consistent snapshot of the entire store while stopped. The small backup below covers keys, configuration and the old executable.

Stop this node.

```bash
sudo systemctl stop celestia-light
```

Confirm its process has exited. Continue only if this succeeds.

```bash
test "$(systemctl show celestia-light --property=MainPID --value)" = "0"
```

Create a private backup directory.

```bash
mkdir -m 0700 "$UPGRADE_DIR/backup"
```

Back up configuration.

```bash
cp -p "$NODE_STORE/config.toml" "$UPGRADE_DIR/backup/config.toml"
```

Back up DA keys. Keep this directory private.

```bash
cp -a "$NODE_STORE/keys" "$UPGRADE_DIR/backup/keys"
```

Keep the previous executable.

```bash
cp -p "$HOME/go/bin/celestia" "$UPGRADE_DIR/backup/celestia"
```

## 4. Install and update configuration

The installation below uses the `$HOME/go/bin` path from our node guide. If ExecStart uses another path, install the binary there instead.

Install the compiled node for this user.

```bash
GOBIN="$HOME/go/bin" make install
```

Install the matching key utility.

```bash
GOBIN="$HOME/go/bin" make install-key
```

Verify the installed release before restarting.

```bash
"$HOME/go/bin/celestia" version
```

Merge new configuration fields into the existing store. This is required when crossing from a version below v0.31.3; review it for every upgrade.

```bash
"$HOME/go/bin/celestia" light config-update --p2p.network mocha --node.store "$NODE_STORE"
```

Compare the old and updated configuration. A diff exit code of 1 means differences were found.

```bash
diff -u "$UPGRADE_DIR/backup/config.toml" "$NODE_STORE/config.toml"
```

Check your core endpoint, TLS mode, pruning, RPC authentication and listener addresses. Keep the existing store; do not run `init` or `unsafe-reset-store` as an upgrade step.

## 5. Start and verify

Start the existing unit with its saved flags.

```bash
sudo systemctl start celestia-light
```

Check the service state.

```bash
sudo systemctl status celestia-light --no-pager
```

Inspect startup and synchronization messages.

```bash
sudo journalctl -u celestia-light -n 100 --no-pager
```

Confirm that peers connect, headers advance, and sampling resumes. A running service alone does not prove the node is healthy. Keep the same confirmed gRPC address and TLS settings.

If startup fails, stop the service and read the first error. Do not overwrite the store or blindly downgrade after a datastore migration. Retain the backup and follow the release's recovery guidance.

Sources: [Official installation and upgrade instructions](https://docs.celestia.org/operate/data-availability/install-celestia-node/), [configuration update](https://docs.celestia.org/operate/maintenance/troubleshooting/), [release notes](https://github.com/celestiaorg/celestia-node/releases/tag/v0.34.3-mocha).