proxmox/docs/09-troubleshooting/RPC_2500_QUICK_FIX.md

RPC-01 (VMID 2500) Quick Fix Guide

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Container: besu-rpc-1
VMID: 2500
IP: 192.168.11.250

---

🚀 Quick Fix (Automated)

Run the automated fix script:

cd /home/intlc/projects/proxmox
./scripts/fix-rpc-2500.sh

This script will:

1. ✅ Check container status
2. ✅ Stop service
3. ✅ Create/fix configuration file
4. ✅ Remove deprecated options
5. ✅ Enable RPC endpoints
6. ✅ Update service file
7. ✅ Start service
8. ✅ Test RPC endpoint

---

🔍 Quick Diagnostic

Run the troubleshooting script first to identify issues:

cd /home/intlc/projects/proxmox
./scripts/troubleshoot-rpc-2500.sh

---

📋 Common Issues & Quick Fixes

Issue 1: Configuration File Missing

Error: Unable to read TOML configuration, file not found

Quick Fix:

pct exec 2500 -- bash -c "cat > /etc/besu/config-rpc.toml <<'EOF'
data-path=\"/data/besu\"
genesis-file=\"/genesis/genesis.json\"
network-id=138
p2p-host=\"0.0.0.0\"
p2p-port=30303
miner-enabled=false
sync-mode=\"FULL\"
rpc-http-enabled=true
rpc-http-host=\"0.0.0.0\"
rpc-http-port=8545
rpc-http-api=[\"ETH\",\"NET\",\"WEB3\"]
rpc-http-cors-origins=[\"*\"]
rpc-ws-enabled=true
rpc-ws-host=\"0.0.0.0\"
rpc-ws-port=8546
rpc-ws-api=[\"ETH\",\"NET\",\"WEB3\"]
rpc-ws-origins=[\"*\"]
metrics-enabled=true
metrics-port=9545
metrics-host=\"0.0.0.0\"
logging=\"INFO\"
permissions-nodes-config-file-enabled=true
permissions-nodes-config-file=\"/permissions/permissions-nodes.toml\"
static-nodes-file=\"/genesis/static-nodes.json\"
discovery-enabled=true
privacy-enabled=false
rpc-tx-feecap=\"0x0\"
max-peers=25
tx-pool-max-size=8192
EOF"

pct exec 2500 -- chown besu:besu /etc/besu/config-rpc.toml
pct exec 2500 -- systemctl restart besu-rpc.service

---

Issue 2: Deprecated Configuration Options

Error: Unknown options in TOML configuration file

Quick Fix:

# Remove deprecated options
pct exec 2500 -- sed -i '/^log-destination/d' /etc/besu/config-rpc.toml
pct exec 2500 -- sed -i '/^max-remote-initiated-connections/d' /etc/besu/config-rpc.toml
pct exec 2500 -- sed -i '/^trie-logs-enabled/d' /etc/besu/config-rpc.toml
pct exec 2500 -- sed -i '/^accounts-enabled/d' /etc/besu/config-rpc.toml
pct exec 2500 -- sed -i '/^database-path/d' /etc/besu/config-rpc.toml
pct exec 2500 -- sed -i '/^rpc-http-host-allowlist/d' /etc/besu/config-rpc.toml

# Restart service
pct exec 2500 -- systemctl restart besu-rpc.service

---

Issue 3: Service File Wrong Config Path

Error: Service references wrong config file

Quick Fix:

# Check what service expects
pct exec 2500 -- grep "config-file" /etc/systemd/system/besu-rpc.service

# Update service file
pct exec 2500 -- sed -i 's|--config-file=.*|--config-file=/etc/besu/config-rpc.toml|' /etc/systemd/system/besu-rpc.service

# Reload systemd
pct exec 2500 -- systemctl daemon-reload

# Restart service
pct exec 2500 -- systemctl restart besu-rpc.service

---

Issue 4: RPC Not Enabled

Quick Fix:

# Enable RPC HTTP
pct exec 2500 -- sed -i 's/rpc-http-enabled=false/rpc-http-enabled=true/' /etc/besu/config-rpc.toml

# Enable RPC WebSocket
pct exec 2500 -- sed -i 's/rpc-ws-enabled=false/rpc-ws-enabled=true/' /etc/besu/config-rpc.toml

# Restart service
pct exec 2500 -- systemctl restart besu-rpc.service

---

✅ Verification

After fixing, verify:

# Check service status
pct exec 2500 -- systemctl status besu-rpc.service

# Check if ports are listening
pct exec 2500 -- ss -tlnp | grep -E "8545|8546"

# Test RPC endpoint
pct exec 2500 -- curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

---

📚 Full Documentation

For detailed troubleshooting, see:

• RPC 2500 Troubleshooting Guide
• Troubleshooting FAQ

---

Last Updated: $(date)