Ergo Node Troubleshooting Guide

Troubleshoot common issues with the Ergo reference client. If your problem isn't covered, create a new issue on GitHub and provide details (node version, Java command, system specs, logs, etc).

Back to Setup #node Discord

Searching the Logs

Use these commands to search your logs for errors and warnings:

ERROR & WARN to file
tail -Fn+0 ergo.log | grep 'ERROR\|WARN' > output.log
ERROR & WARN
tail -Fn+0 ergo.log | grep 'ERROR\|WARN'
ERROR only
tail -Fn+0 ergo.log | grep 'ERROR'
not modified
tail -Fn+0 ergo.log | grep "not modified"
ERR
tail -Fn+0 ergo.log | grep ERR
xception
tail -Fn+0 ergo.log | grep xception
stuck
tail -Fn+0 ergo.log | grep "stuck"

Synchronization Issues

Stuck on 'Active Synchronization'

  1. Use the log commands above to check for errors.
  2. Shut down your node, back up your data, and restart.
  3. Ask for help in #node Discord or open a GitHub issue.

Node Appears 'Synchronized' But Isn't

If your node's height doesn't match the explorer, add this to your ergo.conf:

# headerChainDiff = 80

See also header download issue.

Lowering maxConnections

To improve performance, lower maxConnections in ergo.conf:

network {
  maxConnections = 10
}

This slows sync but may help stability.

Resyncing From Scratch

Remove these directories and restart the node:

rm -rf .ergo/state
rm -rf .ergo/history

Warning: This will delete your local blockchain data.

API Performance Issues

Timeouts or Unresponsiveness

  • Increase JVM memory with -Xmx6G or -Xmx8G in your Java command.
  • Check system load (CPU, RAM, disk I/O).
  • Digest mode may limit some API queries.
  • Check network latency.
  • See GitHub issues for endpoint bugs.
java -jar -Xmx6G ergo-*.jar --mainnet -c ergo.conf

Wallet Issues

Correct Address/Balance Not Displayed

  1. Ensure the wallet is synchronized.
  2. Derive new addresses as per swagger instructions.
  3. Derive additional addresses during sync.
  4. If issues persist, restore the wallet on a different client.

Common Error Messages

'Unable to Define External Address'

WARN [tor.default-dispatcher-11] s.c.n.NetworkController - Unable to define external address. Specify it manually in scorex.network.declaredAddress

This is normal for non-public nodes. Ignore if not running a public node.

'Got GetReaders Request in State None'

WARN  [ergoref-api-dispatcher-9] o.e.n.ErgoReadersHolder Got GetReaders request in state (None,None,None,None)

Normal at startup. If persistent, resync by removing .ergo/state and .ergo/history.

'Invalid Z Bytes'

cat ergo.log | grep -A 30 -B 30 "Invalid z bytes"

Shows log context for this error.

'Dead Letters'

tail -Fn+0 ergo.log | grep "akka.log-dead-letters"

Akka dead letters are usually harmless.

'Failed to Connect to localhost Port 9053: Connection Refused'

netstat -ln | grep 9053
sudo netstat -tulpn

Check if the node is running and port is open.

'Tree Root Should Be Real'

This means you're trying to sign a box you don't own (missing private key).

Public Nodes & Explorers

Known Public Resources

Troubleshooting Public Infrastructure

  1. Switch to a different public node/explorer.
  2. Check status on ergonodes.net or explorer site.
  3. Look for reports in community channels (Discord, Telegram).
  4. If possible, contact the operator or report in general channels with details (URL, error, time, etc).
  5. Check GitHub issues for known problems.
  6. Remember: public services may have downtime or limits. For critical use, run your own node.