🔍 Tronsell Wiki

Full Node Troubleshooting

Complete diagnostic and repair guide for TRON full nodes. Identify root causes of sync failures, memory errors, peer disconnections, database corruption, and performance degradation — with step-by-step solutions.

Updated: June 2025 ~15 min read Operations · Expert

🔍 Troubleshooting at a Glance

Most Common Issue Sync stuck / lagging

Primary Cause Insufficient resources / network

Quick Fix Restart + snapshot

OOM Fix Increase heap + G1GC

Database Repair DbRecover tool

Last Resort Re-sync from snapshot

🔬 Diagnostic Approach

Before diving into specific fixes, follow this systematic diagnostic process:

1. Check the logs — tail -f /opt/tron-node/logs/tron.log for ERROR or WARNING messages.
2. Verify system resources — CPU, memory, disk space, and network.
3. Check sync status — Compare your node's block height with Tronscan.
4. Test API endpoints — Ensure HTTP and gRPC ports are responsive.
5. Review recent changes — Did you upgrade, change config, or modify the environment?

                    # Quick health check commands
                    curl -s localhost:8090/wallet/getnowblock | jq '.block_header.raw_data.number'
                    df -h /opt/tron-node
                    free -h
                    top -bn1 | head -15
                    tail -50 /opt/tron-node/logs/tron.log | grep -E "ERROR|WARN"
                

⏳ Sync Issues

Sync problems are the most common issue with TRON full nodes. Here's how to diagnose and fix them.

Symptom	Likely Cause	Solution
Node stuck at a specific block	Database corruption or bad peer	Restart node; if persists, restore from snapshot
Slow sync (< 10 blocks/min)	Disk I/O bottleneck, low RAM, or HDD	Upgrade to NVMe SSD, increase heap, use RocksDB
Frequent peer disconnections	Network issues, firewall, or stale peers	Check firewall, add seed IPs, increase peer limit
Sync restarts from genesis	Corrupted database or config change	Restore snapshot or re-sync with clean database
Node falls behind after being synced	Resource contention or network lag	Increase JVM heap, check CPU/network usage

⚡ Fast Recovery

If your node is more than 10,000 blocks behind, the fastest recovery is to restore from a recent snapshot. This takes hours instead of days.

🧠 Memory & OOM Issues

Out-of-memory (OOM) errors are common when the JVM heap is too small or the server has insufficient RAM.

Symptoms

java.lang.OutOfMemoryError: Java heap space
Node crashes with exit code 137 (killed by OOM killer).
Extremely slow sync with frequent GC pauses.
Swap usage > 0 (indicates memory pressure).

Solutions

Increase heap size — For 32 GB servers, use -Xmx20G -Xms20G.
Switch to G1GC — -XX:+UseG1GC -XX:MaxGCPauseMillis=200.
Reduce RocksDB memory — Lower db.blockCacheSize to 1024 MB.
Add more RAM — If your server has < 16 GB, consider upgrading.

                    # Example JVM settings for OOM prevention
                    java -Xmx20G -Xms20G -XX:+UseG1GC -XX:MaxGCPauseMillis=200 \
                      -XX:+DisableExplicitGC -XX:MaxDirectMemorySize=4G \
                      -jar FullNode.jar -c config.conf
                

💡 Monitor GC

Add -Xlog:gc*:file=gc.log:time,uptime:filecount=10,filesize=100M to log GC activity and diagnose memory issues.

🌐 Peer & Network Issues

A healthy node needs at least 5–10 active peers. Common peer issues and fixes:

🔌

Port Blocked

Ensure port 18888 is open and reachable. Use telnet to test from outside.

📡

Low Peer Count

Increase maxActiveNodes = 30 and add seed IPs in config.conf.

🔄

Stale Peers

Restart the node to flush peer cache. Use the /wallet/listnodes API to inspect peers.

⚠️

High Latency

Choose peers in the same geographic region. Monitor ping latency to peers.

                    # Add seed IPs in config.conf
                    node.p2p.seedIP = [
                      "35.177.64.181:18888",
                      "35.177.201.46:18888",
                      "35.177.202.101:18888"
                    ]
                

💥 Database Corruption

Database corruption can occur due to power outages, disk failures, or improper shutdowns. Symptoms include:

java.lang.IllegalStateException: Could not open database
Corruption: ... in logs
Node crashes immediately after startup
Sync stuck at a specific block

Recovery Steps

Stop the node

sudo systemctl stop tron-node

Run RocksDB recovery tool

java -cp FullNode.jar org.rocksdb.tools.DbRecover -db /opt/tron-node/database

If recovery fails, restore from snapshot

Download a fresh snapshot and extract it to the database directory.

Start the node

sudo systemctl start tron-node

⚠️ Prevention

Always shut down the node gracefully with systemctl stop. Use a UPS and RAID for critical nodes. Regular snapshots are your best defense.

🐌 Performance Degradation

If your node is running but performing poorly, check these areas:

Metric	Warning Sign	Fix
CPU Usage	> 90% sustained	Reduce peer count, lower log level, upgrade CPU
Disk I/O	High await time (> 20 ms)	Upgrade to NVMe, reduce compaction threads
Network	High retransmission rate	Check firewall, upgrade bandwidth
GC Pauses	> 1 second frequently	Increase heap, tune G1GC, use ZGC
Block Lag	> 10 blocks	Check all of the above

📋 Common Error Codes & Messages

Error Message	Meaning	Solution
Could not open database	Database corruption or lock issue	Run DbRecover or restore snapshot
Out of memory	JVM heap exhausted	Increase -Xmx, tune GC
Connection refused	Port not open or node not listening	Check firewall, verify node is running
No such peer	Peer disconnected or not reachable	Check network, add more seed IPs
Invalid block header	Potential fork or corrupted block	Restart node; if persists, re-sync
Too many open files	File descriptor limit too low	Increase ulimit -n to 65536

📋 Recovery Playbook: Quick Reference

🟢

Minor Lag (< 100 blocks)

Wait — the node will catch up. Check logs for errors. Restart if no progress after 1 hour.

🟡

Moderate Lag (100–1,000 blocks)

Restart the node. Check peers and network. Increase maxActiveNodes if needed.

🔴

Severe Lag (> 1,000 blocks)

Restore from a recent snapshot. This is the fastest recovery method.

💀

Node Won't Start

Check logs for specific errors. Try DbRecover. If all else fails, re-sync from snapshot.

❓ Frequently Asked Questions

Why is my TRON node stuck at a certain block?

This is usually caused by database corruption, a bad peer, or a network partition. Try restarting the node first. If the issue persists, check logs for errors and consider restoring from a snapshot.

What should I do if my node runs out of memory?

Increase the JVM heap with -Xmx (e.g., -Xmx20G for a 32 GB server). Switch to G1GC or ZGC. Also consider reducing RocksDB's block cache size to free memory.

How can I tell if my node is synced?

Call /wallet/getnowblock and compare the returned block number with the latest block on Tronscan. If the difference is less than 5 blocks, your node is synced.

How do I recover from a corrupted RocksDB database?

Use the built-in DbRecover tool: java -cp FullNode.jar org.rocksdb.tools.DbRecover -db /path/to/database. If recovery fails, restore from a snapshot.

Why do I keep losing peers?

Common causes: firewall blocking port 18888, stale peer list, or network instability. Check that the port is open, increase maxActiveNodes, and add reliable seed IPs.

⚡ Keep Your Node Healthy

Troubleshooting your node? Pair it with Tronsell Energy to power your dApps and transactions at the lowest cost.

⚡ Get Tron Energy 📞 Contact Support