Skip to main content

Planq Troubleshooting Guide

This guide helps you diagnose and resolve common issues with your Planq node.

Quick Diagnostics​

Before diving into specific issues, run this diagnostic script:

quick-diagnostics.sh
#!/bin/bash
echo "=== Planq Node Diagnostics ==="
echo ""

# Check if service is running
echo "1. Service Status:"
systemctl is-active planqd && echo "✅ Service is running" || echo "❌ Service is not running"
echo ""

# Check disk space
echo "2. Disk Space:"
df -h | grep -E "^/dev|Filesystem"
echo ""

# Check memory
echo "3. Memory Usage:"
free -h
echo ""

# Check peers
echo "4. Connected Peers:"
curl -s localhost:26657/net_info | jq .result.n_peers 2>/dev/null || echo "❌ Cannot connect to RPC"
echo ""

# Check sync status
echo "5. Sync Status:"
curl -s localhost:26657/status | jq .result.sync_info.catching_up 2>/dev/null || echo "❌ Cannot get sync status"
echo ""

# Check EVM RPC
echo "6. EVM RPC Status:"
curl -s localhost:8545 -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | jq . 2>/dev/null || echo "❌ EVM RPC not responding"
echo ""

# Check recent errors
echo "7. Recent Errors (last 20):"
journalctl -u planqd --no-pager | grep -i error | tail -20

Common Issues and Solutions​

1. Node Won't Start​

Symptoms:

  • Error: listen tcp :26656: bind: address already in use
  • Error: listen tcp :8545: bind: address already in use

Solution:

# Find processes using the ports
sudo lsof -i :26656
sudo lsof -i :8545

# Kill the processes (replace PID with actual process ID)
sudo kill -9 PID

# Or change the ports in config
sed -i 's/:26656/:26756/g' ~/.planqd/config/config.toml
sed -i 's/:8545/:8645/g' ~/.planqd/config/app.toml

2. Sync Issues​

Symptoms:

  • Block height not increasing
  • catching_up: true for extended period

Solution:

# 1. Check if you have peers
curl -s localhost:26657/net_info | jq .result.n_peers

# 2. If no peers, add seeds/peers
SEEDS="dd2f0ceaa0b21491ecae17413b242d69916550ae@135.125.5.31:26656,0525de7e7640008d2a2e01d1a7f6456f28f3324c@51.79.142.6:26656"
PEERS="$(curl -s https://raw.githubusercontent.com/planq-network/networks/main/mainnet/peers.txt | tr '
' ',')"

sed -i "s/seeds = \"\"/seeds = \"$SEEDS\"/g" ~/.planqd/config/config.toml
sed -i "s/persistent_peers = \"\"/persistent_peers = \"$PEERS\"/g" ~/.planqd/config/config.toml

# 3. Restart the node
sudo systemctl restart planqd

# 4. If still stuck, try state sync or snapshot restore

3. EVM Issues​

Symptoms:

  • Cannot connect to port 8545
  • EVM transactions failing

Solution:

# 1. Check if EVM is enabled
grep -A 10 "\[evm\]" ~/.planqd/config/app.toml

# 2. Enable EVM if disabled
sed -i 's/enable = false/enable = true/g' ~/.planqd/config/app.toml

# 3. Check EVM configuration
# In ~/.planqd/config/app.toml:
# [json-rpc]
# enable = true
# address = "0.0.0.0:8545"

# 4. Restart the node
sudo systemctl restart planqd

# 5. Test EVM connection
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
http://localhost:8545

4. High Resource Usage​

Symptoms:

  • CPU constantly at 100%
  • Node becomes unresponsive

Solution:

# 1. Check what's consuming CPU
top -p $(pgrep planqd)

# 2. Reduce mempool size
sed -i 's/size = 5000/size = 1000/g' ~/.planqd/config/config.toml

# 3. Disable unnecessary features
# In ~/.planqd/config/config.toml:
# index_all_keys = false
# prometheus = false

# In ~/.planqd/config/app.toml:
# [json-rpc]
# enable-indexer = false

# 4. Restart with limits
sudo systemctl edit planqd
# Add:
# [Service]
# CPUQuota=80%

5. Network Issues​

Symptoms:

  • Peer count is 0
  • Cannot sync with network

Solution:

# 1. Check firewall settings
sudo ufw status
sudo ufw allow 26656/tcp

# 2. Add seed nodes
SEEDS="dd2f0ceaa0b21491ecae17413b242d69916550ae@135.125.5.31:26656"
sed -i "s/seeds = \"\"/seeds = \"$SEEDS\"/g" ~/.planqd/config/config.toml

# 3. Clear peer store
sudo systemctl stop planqd
rm -rf ~/.planqd/data/peerstore.db
sudo systemctl start planqd

# 4. Check network connectivity
ping rpc.planq.network

Performance Optimization​

System Tuning​

# Increase file descriptors
echo "fs.file-max = 65535" | sudo tee -a /etc/sysctl.conf
ulimit -n 65535

# Network optimization
echo "net.core.rmem_default = 262144" | sudo tee -a /etc/sysctl.conf
echo "net.core.rmem_max = 16777216" | sudo tee -a /etc/sysctl.conf

# Apply changes
sudo sysctl -p

Database Optimization​

# Use faster database backend
# In ~/.planqd/config/config.toml:
# db_backend = "pebbledb"

# Enable pruning to save disk space
# In ~/.planqd/config/app.toml:
# pruning = "default"
# pruning-keep-recent = "100"
# pruning-interval = "10"

Emergency Procedures​

Complete Reset​

# WARNING: This will delete all local data
sudo systemctl stop planqd
planqd tendermint unsafe-reset-all
sudo systemctl start planqd

Backup and Restore​

# Create backup
sudo systemctl stop planqd
tar -czf planq-backup-$(date +%Y%m%d).tar.gz ~/.planqd
sudo systemctl start planqd

# Restore from backup
sudo systemctl stop planqd
rm -rf ~/.planqd
tar -xzf planq-backup-YYYYMMDD.tar.gz -C ~/
sudo systemctl start planqd

Getting Help​

If you're still experiencing issues:

  1. Check the logs: journalctl -u planqd -f
  2. Visit the documentation: Planq Docs
  3. Join the Discord: Planq Discord
  4. Search GitHub issues: Planq Issues

When asking for help, always include:

  • Your OS and version
  • Node version: planqd version
  • Error logs from the last 50 lines: journalctl -u planqd -n 50
  • Your node status: curl -s localhost:26657/status | jq .result.sync_info
  • EVM status: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http://localhost:8545