Troubleshooting

Ports

When interacting with a Celestia node, you may need to open ports on your machine to allow communication between nodes, such as bridge nodes. It is essential that specific ports are accessible. Make sure that your firewall allows connections to the correct ports.

If you run a node on a cloud server, make sure that the ports are open on the server's firewall. If you run a node at home, make sure that your router allows connections to the correct ports.

For example, validator ports 9090 and 26657 need to be accessible by the bridge, and port 2121 is required for P2P connections for all node types.

The following ports are used by Celestia nodes:

Port	Protocol	Address	Description	Enabled by default on node	Flag
2121	TCP/UDP	localhost	P2P	true	N/A
26658	HTTP	localhost	RPC	true	--rpc.port string
26659	HTTP	localhost	REST Gateway	false	--gateway.port string

caution

The gateway endpoints have been deprecated and will be removed in the future. If you would like to use them anyway, you can find more details here.

Changing the location of your node store

In this section, we'll guide you through starting your node using a node store in a different location than you originally started with.

First, stop your node safely using control + C.

Then, init your node again with a new node store:

celestia <node-type> init --node.store /home/user/celestia-<node-type>-location/ --p2p.network blockspacerace

Next, start your node:

celestia full start --core.ip rpc-blockspacerace.pops.one --p2p.network blockspacerace --node.store /home/user/celestia-<node-type>-location/

If you choose to change the location of your node store, you will need to execute each command on your node with the following flag:

--node.store /home/user/celestia-<node-type>-location/

When using cel-key, the process is different. To show the keys you should add --keyring-dir like this example:

./cel-key list --p2p.network blockspacerace --node.type full --keyring-dir /home/user/celestia-<node-type>-location/keys/

Network selection

Note: If you do not select a network, the default network will be 'Mocha'.

celestia <node-type> init --p2p.network <network>
celestia <node-type> start --p2p.network <network> --core.ip <address> <port>

tip

Please refer to the ports section for information on which ports are required to be open on your machine.

NOTE: It is advised before switching networks to reinitialize your node via init command. This is due to an old config being present. Re-initialisation will reset the config.

Resetting your config

If you an encounter an error, it is likely that an old config file is present:

Error: nodebuilder/share: interval must be positive; nodebuilder/core: invalid IP addr given:

# or

Error: nodebuilder/share: interval must be positive

You can re-initialize your node's config with the following commands:

tip

Save your config so custom values are not lost.

v0.9.1 and later

All node types on v0.9.1 and later

Run the following command to update your config:

celestia <node-type> config-update --p2p.network <network>

This will pull in any new values from new configuration and merge them into the existing configuration.

tip

After using the config-update command, it is encouraged to double-check that your custom values are preserved.

Then, to start your node again:

celestia <node-type> start --p2p.network <network>

v0.9.0 and earlier

All node types on v0.9.0 and earlier

1. First, remove your config:

rm ~./<path-to-node-store>/config.toml

2. Re-initialize the node:

celestia <node-type> init --p2p.network <network>

tip

If you have saved any custom values, add them back to the config.

3. Start the node:

celestia <node-type> start --p2p.network <network>

tip

Please refer to the ports section for information on which ports are required to be open on your machine.

Clearing the data store

v0.9.0 and later

Version 0.9.0+

For bridge, full, and light nodes, remove the data store with this command:

celestia <node-type> unsafe-reset-store --p2p.network <network>

Example for light node on Blockspace Race on v0.9.0+

celestia light unsafe-reset-store --p2p.network blockspacerace

v0.8.2 and earlier

Bridge and full nodes v0.8.2 and earlier

danger

Make sure not to remove anything except the directories listed below.

1. First, remove the data store:

rm -rf ~./<path-to-node-store>/data
rm -rf ~./<path-to-node-store>/transients
rm -rf ~./<path-to-node-store>/index
rm -rf ~./<path-to-node-store>/blocks

2. Re-initialize the node:

celestia <node type> init --p2p.network <network>

3. Start the node:

celestia <node type> start --p2p.network <network>

tip

Please refer to the ports section for information on which ports are required to be open on your machine.

Light nodes v0.8.2 and earlier

danger

Make sure not to remove anything except the <path-to-node-store>/data directory.

1. First, remove the data store:

rm -rf ~./<path-to-node-store>/data

2. Re-initialize the node:

celestia light init --p2p.network <network>

3. Start the node:

celestia light start --p2p.network <network>

tip

Please refer to the ports section for information on which ports are required to be open on your machine.

Example for Blockspace Race on v0.8.2 and earlier

Here's an example for clearing the data store on Blockspace Race with a light node:

danger

Make sure not to remove anything except the <path-to-node-store>/data directory.

rm -rf ~./celestia-light-blockspacerace-0/data
celestia light init --p2p.network blockspacerace

Your output will look similar to below:

2022-11-01T22:23:19.581+0100	INFO	node	nodebuilder/init.go:20	Initializing Light Node Store over '/Users/joshstein/.celestia-light-blockspacerace-0'
2022-11-01T22:23:19.582+0100	INFO	node	nodebuilder/init.go:51	Saving config	{"path": "/Users/joshstein/.celestia-light-blockspacerace-0/config.toml"}
2022-11-01T22:23:19.582+0100	INFO	node	nodebuilder/init.go:52	Node Store initialized

Then start your node:

celestia light start --p2p.network blockspacerace --core.ip <address>

tip

Please refer to the ports section for information on which ports are required to be open on your machine.

FATAL headers given to the heightSub are in the wrong order

If you observe a FATAL log line like:

FATAL	header/store	store/heightsub.go:87	PLEASE FILE A BUG REPORT: headers given to the heightSub are in the wrong order"

then it is possible the celestia-node data/ directory contains headers from a previous instance of the network that you are currently trying to run against. One resolution strategy is to delete the existing celestia-node config for the target network and re-initialize it:

# rm -rf ~/.celestia-<node-type>-<network>
rm -rf ~/.celestia-bridge-private

# celestia <node-type> init --p2p.network <network>
celestia bridge init --p2p.network private