Troubleshooting

Common issues and solutions when running Evolve nodes.

Diagnostic Commands

Check Node Status

# Health check
curl http://localhost:7331/health/live
curl http://localhost:7331/health/ready

# Node status
curl http://localhost:26657/status

View Logs

If running in the foreground, logs are printed to stderr by default. If running as a background service, use the appropriate command:

# foreground (default in dev)
./evnode start ... 2>&1 | tee evnode.log

# systemd service
journalctl -u evnode -f

# docker container
docker logs -f <container_name>

Common Issues

Node Won't Start

Symptom: Node exits immediately after starting.

Solutions:

1. Check for port conflicts:

lsof -i :26657
lsof -i :7676

1. Verify configuration file syntax:

cat ~/.evnode/config/evnode.yml

1. Check data directory permissions:

ls -la ~/.evnode/data

DA Connection Failures

Symptom: Logs show DA layer submission failed errors.

Error example:

ERR DA layer submission failed error="connection refused"

Solutions:

1. Verify DA endpoint is reachable:

curl http://localhost:26658/health

1. Check authentication token (Celestia):

celestia light auth write --p2p.network mocha

1. Verify DA node is fully synced:

celestia header sync-state

Out of DA Funds

Symptom: Code: 19 errors in logs.

Error example:

ERR DA layer submission failed error="Codespace: 'sdk', Code: 19, Message: "

Solutions:

1. Check DA account balance
2. Fund the account with more tokens
3. Increase gas price to unstick pending transactions:

--evnode.da.gas_price 0.05

See Restart Chain Guide for detailed steps.

P2P Connection Issues

Symptom: Node not syncing, no peers connected.

Solutions:

1. Verify peer address format:

# Correct format
/ip4/1.2.3.4/tcp/7676/p2p/12D3KooWABC...

# NOT just the peer ID
12D3KooWABC...

1. Check firewall allows P2P port:

sudo ufw status
# Ensure port 7676 (or your P2P port) is allowed

1. Try DA-only sync mode (no P2P):

evnode start --evnode.da.address http://localhost:26658
# Leave --evnode.p2p.peers empty

Node Falling Behind

Symptom: catching_up: true in status, height increasing slowly.

Solutions:

1. Check system resources:

htop
df -h

1. Increase DA request timeout:

--evnode.da.request_timeout 60s

1. Verify DA layer is responding quickly:

time curl http://localhost:26658/header/sync_state

Execution Layer Desync

Symptom: State root mismatches, execution errors.

EVM (ev-reth):

# Check ev-reth logs for errors
journalctl -u ev-reth -f

# Verify Engine API connectivity
curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(cat jwt.hex)" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8551

Cosmos SDK (ev-abci):

# Check app hash consistency
curl http://localhost:26657/status | jq '.sync_info'

Reset Procedures

Soft Reset (Keep Genesis)

Reset state while keeping configuration:

# Stop the node
systemctl stop evnode

# Clear data directory
rm -rf ~/.evnode/data/*

# Restart
systemctl start evnode

Hard Reset (Full Reinitialize)

Complete reset including configuration:

# Stop the node
systemctl stop evnode

# Remove everything
rm -rf ~/.evnode

# Reinitialize
evnode init

Reset EVM State (ev-reth)

# Stop both nodes
systemctl stop evnode ev-reth

# Clear ev-reth data
rm -rf ~/.ev-reth/db

# Clear ev-node cache
rm -rf ~/.evnode/data/cache

# Restart
systemctl start ev-reth evnode

Performance Issues

High Memory Usage

1. Reduce cache size in configuration
2. Enable lazy aggregation mode
3. Limit max pending blocks:

--evnode.node.max_pending_blocks 50

High CPU Usage

1. Increase block time:

--evnode.node.block_time 2s

1. Check for transaction spam
2. Monitor execution layer performance

Disk Space

1. Check disk usage:

du -sh ~/.evnode/data/*

1. Prune old data (if supported by execution layer)
2. Consider moving data to larger disk

Getting Help

1. Check logs for specific error messages
2. Search GitHub Issues
3. Join the community Discord for support

See Also

• Reset State Guide - Detailed reset procedures
• Restart Chain Guide - Restarting after issues
• Monitoring Guide - Proactive monitoring