Upgrade

Update your Celestia light node while keeping its existing store.

Mainnet · Chain ID celestia · Checked 13 October 2026

Target release: v0.34.3. Check Versions and the release notes before each upgrade.

This procedure follows the native systemd installation in Light Node. 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.

sudo systemctl cat celestia-light

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

"$HOME/go/bin/celestia" version

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

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

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

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.

go version

2. Build the selected release

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

Choose the network-specific release.

NODE_VERSION="v0.34.3"

Create a fresh working directory.

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

Download the source for the selected tag.

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

Enter the source directory.

cd "$UPGRADE_DIR/source"

Compile the node binary.

make build

Compile the matching key utility.

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.

sudo systemctl stop celestia-light

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

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

Create a private backup directory.

mkdir -m 0700 "$UPGRADE_DIR/backup"

Back up configuration.

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

Back up DA keys. Keep this directory private.

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

Keep the previous executable.

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.

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

Install the matching key utility.

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

Verify the installed release before restarting.

"$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.

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

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

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.

sudo systemctl start celestia-light

Check the service state.

sudo systemctl status celestia-light --no-pager

Inspect startup and synchronization messages.

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, configuration update, release notes.