Troubleshooting

Common issues • Diagnostic commands • Solutions for node problems • Get help

Common Issues & Solutions

Running into problems? This guide covers the most common issues node operators face and provides step-by-step solutions to get you back online.

Java Installation Issues

Java not found

If you get "java: command not found":

sudo apt install openjdk-21-jre-headless -y

Wrong Java version

Check your Java version:

java -version

You need Java 17 or higher. If you have an older version, install a newer one:

sudo apt install openjdk-21-jre-headless -y

Multiple Java versions installed

If you have multiple Java versions, set the default:

sudo update-alternatives --config java
# Select the Java 17 or 21 option

Port & Firewall Issues

Port already in use

Check what's using the port:

sudo lsof -i :9000

If another process is using it, you can kill it:

# Find the PID from the lsof output
sudo kill -9 <PID>

Firewall blocking connections

Check firewall status:

sudo ufw status

Make sure these ports are open:

sudo ufw allow 22/tcp      # SSH
sudo ufw allow 9000/tcp    # Public HTTP
sudo ufw allow 9001/tcp    # P2P
sudo ufw allow 9002/tcp    # CLI
sudo ufw enable

Connection refused on port 9002

The CLI port (9002) only accepts connections from localhost (127.0.0.1). Make sure you're running the join command from the same server, not remotely.

Correct usage (from the server itself):

curl -X POST http://127.0.0.1:9002/cluster/join ...

Node Won't Start

Keystore file not found

Verify your keystore file exists:

ls -la ~/reality-node/node.p12

If it doesn't exist, you need to generate it:

cd ~/reality-node
java -jar reality-keytool-assembly-*.jar generate \
  --keystore node.p12 \
  --keyalias node \
  --password YOUR_SECURE_PASSWORD

Wrong password

If you get authentication errors, double-check your password in:

• Systemd service file: /etc/systemd/system/reality-node.service
• Your java command if using tmux

Out of memory errors

If you see OutOfMemoryError, your server might not have enough RAM. Check memory usage:

free -h

You can reduce the memory allocation in your start command:

# Change from -Xms2g -Xmx2g to:
java -Xms1g -Xmx1g -jar reality-core-assembly-*.jar ...

Minimum 8GB RAM is recommended. Running with less may cause instability.

Check systemd logs for errors

journalctl -u reality-node -n 100 --no-pager

Look for error messages in the output

Can't Join the Cluster

Node not in ReadyToJoin state

Before joining, verify your node is ready:

curl http://YOUR_SERVER_IP:9000/node/info

The state should be "ReadyToJoin". If it's not, wait a minute and check again. If it stays in another state, check the logs.

Bootstrap nodes unreachable

Test connectivity to bootstrap nodes:

# Test genesis node
curl http://143.110.227.9:9000/node/info

# Test validator 1 (if genesis fails)
curl http://68.183.10.93:9000/node/info

# Test validator 2 (if both above fail)
curl http://128.199.67.191:9000/node/info

If all three fail, check your network/firewall settings. Your server might be blocking outbound connections.

Ports not forwarded correctly

Port Forwarding Required

Your router/firewall must allow incoming connections on ports 9000, 9001, and 9002.

Test if your ports are open from an external tool like YouGetSignal

Join command returns error

Make sure you're using the correct format:

curl -X POST http://127.0.0.1:9002/cluster/join \
  -H 'Content-type: application/json' \
  -d '{
    "id": "0000003264c7c8503da3d03b6021101a57b5eb933d887bb7e3fbf4b2a57c302dfc5008afb522059b1926e8220de1cfa9388183de60b376a7bd93268990d71157",
    "ip": "143.110.227.9",
    "p2pPort": 9001
  }'

Note: Use 127.0.0.1 (localhost), not your server's public IP

Network & Connection Issues

Node keeps disconnecting

Check your network stability:

# Ping a reliable server
ping -c 10 8.8.8.8

# Check for packet loss

If you see packet loss, contact your VPS provider. A stable internet connection is required.

DNS resolution issues

# Test DNS
nslookup github.com

# If it fails, try changing DNS servers
sudo nano /etc/resolv.conf
# Add: nameserver 8.8.8.8

IPv6 vs IPv4 issues

Reality Network requires IPv4. If your server returns an IPv6 address, make sure to use the -4 flag when getting your IP.

curl -4 -s ifconfig.me

Performance Issues

Node running slow

Check system resources:

# CPU and memory
htop

# Disk I/O
iostat -x 1

# Disk space
df -h

High CPU usage

This is normal during initial sync. If it persists:

• Check if you meet minimum requirements (2 vCPU cores)
• Consider upgrading to a more powerful VPS
• Check logs for errors that might cause excessive processing

Disk space running low

# Check disk usage
du -sh ~/reality-node/*

# Clean up old logs if using systemd
sudo journalctl --vacuum-time=7d

Still Having Issues?

Check the Documentation

Visit docs.realitynet.xyz for official documentation

GitHub Issues

Search or create an issue at github.com/reality-foundation

Community Support

Join the Reality Network community channels for help from other node operators