Skip to main content

Troubleshooting

Node won't start​

Container exits immediately​

Check the logs:

docker compose logs node

Common causes:

ErrorFix
keystore.json not foundRun the init command first (see Docker Setup)
cannot acquire lockAnother node container is running. Run docker rm -f <old-container>
PRIVANET_PASSPHRASE not setEnsure .env file exists with the passphrase
wrong passphraseYou changed your passphrase. Use the original one, or re-init (loses identity)

OOM killed (Exit 137)​

The container was killed by the OS due to out-of-memory. Ensure your server has at least 1 GB RAM and that the Docker memory limit is set to at least 1g:

deploy:
  resources:
    limits:
      memory: 1g

Check memory:

free -h
docker stats --no-stream

Node shows as offline in dashboard​

Check if the node is actually running​

docker compose ps
docker compose logs --tail=20 node

Check port accessibility​

From outside your server:

nc -zv your-server-ip 8336

From your server:

# Check the port is bound
ss -tulpn | grep 8336

Check firewall rules​

sudo ufw status

Port 8336 must be allowed for both TCP and UDP:

sudo ufw allow 8336/tcp
sudo ufw allow 8336/udp

Check if the API is reachable​

The node connects to https://privanet.dev/api/v1. If the API is unreachable from your server:

curl -s https://privanet.dev/api/v1/health

LevelDB lock error​

failed to open datastore: resource temporarily unavailable

This happens when two node containers try to access the same data directory. Fix:

# Find and stop all node containers
docker ps -a | grep node-client
docker rm -f <container-id>

# Remove stale lock file
rm -f /opt/privanet/data/datastore/LOCK

# Restart normally
docker compose up -d

High memory usage​

libp2p keeps connections in memory. High memory is normal during startup (peer discovery) and usually stabilizes after a few minutes.

If memory stays high (>800 MB) after 10 minutes:

  1. Check how many peers are connected (privanet_peers_total metric)
  2. If >100 peers, the network is large — consider upgrading to 2 GB RAM

Node registered but earning 0 PRIVA​

Possible causes:

  1. Uptime below threshold — nodes need >80% uptime in a window to qualify
  2. Tier not matched — your locked liquidity may not meet the tier requirements
  3. Sync in progress — newly registered nodes have a 24h warm-up period
  4. API registration failed — check logs for registration failed errors

Updating the node​

# Pull latest image
docker compose pull

# Restart with new image
docker compose up -d

# Verify the new version is running
docker compose logs --tail=5 node

Getting support​

When reporting an issue, include:

# Useful debug info to share
docker compose logs --tail=100 node > node-logs.txt
docker stats --no-stream
free -h
uname -a