How to keep your Symbol node up and running healthily.

Maintaining a Node

Once you have created a Symbol node, be it manually or using Symbol bootstrap, the node is mostly autonomous. But there is still a little bit of maintenance required, explained in this guide.

Client updates

New Symbol client versions will be released periodically. If you want to benefit from the added features and bugfixes you will need to update your node to use the latest client version.

Additionally, if your node’s client version falls too far behind, other nodes might refuse to connect to it.

The main version to keep track of is the Catapult client version, since this component is used by all peer nodes. Additionally, API nodes need to keep track of the REST component version too.

  • Finding out what are the latest versions:

    Whenever there is a new client version released it will be announced through the Symbol Twitter and the Discord channel. You can also keep an eye on the different GitHub repositories and the compatibility matrix page to know the latest client and REST versions.

  • Finding out your node versions:

    You can find the versions used by your node in the Symbol Explorer nodes list.

    Additionally, if your node is an API node, you can also query it directly:

    • Client version: /node/info endpoint, version property.


      The version is encoded as a single 4-byte integer, where the Most-Significant Byte encodes the Major version, and the rest of bytes are the Minor, the Micro and the Patch version.

      For example, version 16777472 (decimal) is 01000100h (hex), which corresponds to version

    • REST version: /node/server endpoint, restVersion property.

      restVersion is a version string like “2.3.6”, for example.

The exact procedure to update your node depends on how you created it. Read the appropriate section below.

Update nodes created with Bootstrap

If you used Symbol Bootstrap to create your node (following the Running a node guide), keeping it up to date is very simple.

  1. Update Symbol Bootstrap first (see the Using Symbol Bootstrap guide for more details):

    npm install -g symbol-bootstrap
  2. Then move to the folder where the node’s data folder is (typically target) and stop the node.

    The exact stop command depends on whether your node was running in detached mode or not:

    • If you started in detached mode with symbol-bootstrap start --detached:

      From the folder containing the target folder type:

      symbol-bootstrap stop
    • If you did not start in detached mode:

      You must have a terminal running somewhere with all the output from the client. Stop it by pressing Ctrl+C.

  3. Next make a backup copy of the node’s data folder:

    cp -r target target.BAK
  4. Finally, restart the node with the --upgrade flag to update all necessary component versions.

    Add also the --detached flag to start in detached mode if you need it.

    symbol-bootstrap start --upgrade -c custom-presets.yml
  5. Once the node is up and running again, and you verify that the component versions have been updated, you can remove the backup copy.

Update nodes created manually

If you followed the Running a node manually guide, you need to rebuild the Catapult client and keep the previous data folder so the same accounts and cached data is reused.

In summary, you need to:

  • Stop the running Catapult client with Ctrl+C.

  • Update the Catapult client source repository with the latest version and build it again following the Catapult client instructions.

  • Restart the client from the same folder it was initially launched. Data and configuration files will be reused.


The above procedure works but brings the client offline while the new version is being built, which could be a lengthy process.

If you install the client (with make install) instead of running it from the same folder where it is built, though, you have the option to build the new version while the previous one is still running. In this way the service interruption should be minimal.

The steps then would be:

  • Update the Catapult client source repository and build it again.

  • Stop the running Catapult client.

  • Install the new version of the client.

  • Restart the client.

Voting key renewal

If your node is a Voting node it requires a valid voting key to operate. For security these keys expire after 6 months, so you need to renew them as part of the regular node maintenance.

Read the appropriate section about renewing the voting keys depending on whether you used Symbol Bootstrap or not to build your node: