Common_issues

Chapter 45: Common Node Issues

Overview

This chapter covers the most common issues you’ll encounter when running blockchain nodes and how to fix them.

---

45.1 Sync Issues

Node Stuck at Header

Symptoms:

• eth.syncing shows currentBlock but doesn’t progress
• Peer count is healthy

Solutions:

# 1. Restart with fresh database
systemctl stop geth
rm -rf /data/ethereum/geth/chaindata
systemctl start geth

# 2. Try different bootnodes
geth --bootnodes "enr:..."

Very Slow Sync

Symptoms:

• Sync progressing but very slowly

Solutions:

# Increase peer count
--maxpeers 100

# Check CPU/Memory
top

# Use NVMe SSD

---

45.2 Network Issues

No Peers

Symptoms:

• net.peerCount returns 0

Solutions:

# Check firewall
sudo ufw status

# Check port 30303 is open
telnet discovery.ethdisco.net 30303

# Add bootnodes manually
geth --bootnodes "enr:..."

Peers Dropping

Symptoms:

• Peer count fluctuates wildly

Solutions:

• Check network stability
• Increase dial timeout
• Check for IP bans

---

45.3 Performance Issues

High CPU Usage

Solutions:

# Reduce cache
--cache 2048

# Disable metrics if not needed
# (remove --metrics flag)

Out of Memory

Solutions:

# Reduce cache
--cache 4096

# Check available RAM
free -h

# Add swap
sudo fallocate -l 8G /swapfile

Disk Full

Solutions:

# Check disk space
df -h

# Enable pruning
geth --pruneancientstore

# Remove old data
rm -rf /data/ethereum/geth/chaindata/ancient

---

45.4 RPC Issues

RPC Timeout

Solutions:

# Increase timeout in nginx
proxy_read_timeout 300s;

# Check node is not overloaded
# (check CPU, memory)

RPC Returns Errors

Check:

# Check node is synced
eth.syncing

# Check logs
journalctl -fu geth

---

45.5 Database Issues

Database Corruption

Symptoms:

• Node crashes on startup
• Sync fails repeatedly

Solutions:

# Remove chaindata
systemctl stop geth
rm -rf /data/ethereum/geth/chaindata

# Restart sync
systemctl start geth

---

45.6 Quick Diagnostics

Checklist

# 1. Check if running
systemctl status geth
ps aux | grep geth

# 2. Check logs
journalctl -fu geth -n 50

# 3. Check sync status
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'

# 4. Check peer count
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'

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

---

Summary

• Sync issues: Try fresh database, different peers
• Network issues: Check firewall, ports
• Performance: Adjust cache, monitor resources
• RPC issues: Check sync status, node health

---

Next Chapter

In Chapter 46: Debugging Tools & Techniques, we’ll explore debugging.

---

Last Updated: 2026-02-20