Troubleshooting

Common issues and solutions for Viction nodes

Overview

This guide covers common issues encountered when operating Viction nodes and their solutions.

Node Won’t Start

Issue: “Fatal: Failed to unlock account”

Error message:

Fatal: Failed to unlock account 0x1234...5678 (could not decrypt key with given passphrase)

Cause: Incorrect password provided for account unlock

Solutions:

1. Verify password file content:

cat password.txt

2. Try unlocking interactively:

tomo --unlock 0x1234...5678
# Enter password when prompted

3. Check keystore file exists:

ls -la ~/.ethereum/keystore/

Issue: “Fatal: Error starting protocol stack”

Error message:

Fatal: Error starting protocol stack: listen tcp :30303: bind: address already in use

Cause: Another process is using the P2P port

Solutions:

1. Check what’s using the port:

lsof -i :30303
netstat -tulpn | grep 30303

2. Stop the conflicting process or use a different port:

tomo --port 30304

3. Kill existing tomo process:

pkill tomo
# Wait a few seconds
tomo

Issue: “Fatal: Failed to create the protocol stack”

Error message:

Fatal: Failed to create the protocol stack: datadir already used by another process

Cause: Another tomo instance is using the same data directory or a lockfile exists from a crash

Solutions:

1. Check for running instances:

ps aux | grep tomo

2. Remove stale lock file:

rm ~/.ethereum/LOCK

3. Use a different data directory:

tomo --datadir /path/to/different/datadir

Sync Issues

Issue: Node Not Syncing

Symptoms:

• Block number not increasing
• eth_syncing returns false but node is behind
• No peers connected

Solutions:

1. Check peer count:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' \
  http://localhost:8545

If peer count is 0:

2. Verify network connectivity:

ping 8.8.8.8  # Test internet
tomo --bootnodes "enode://..."

3. Check firewall:

# Ensure port 30303 is open
sudo ufw allow 30303/tcp
sudo ufw allow 30303/udp

4. Try different bootnodes:

tomo --bootnodes "enode://node1@ip1:port,enode://node2@ip2:port"

5. Clear peer database and restart:

tomo removedb
tomo

Issue: Slow Sync Speed

Symptoms:

• Syncing takes extremely long time
• Low block import rate

Solutions:

1. Use fast sync mode (if starting from scratch):

tomo --syncmode fast

2. Increase cache size:

tomo --cache 4096  # Increase cache to 4GB

3. Ensure sufficient resources:

• Check CPU usage: top
• Check disk I/O: iostat -x 1
• Check available memory: free -h

4. Use SSD storage: Move datadir to SSD if currently on HDD:

tomo --datadir /path/to/ssd/datadir

5. Increase max peers:

tomo --maxpeers 50

Issue: Sync Stuck at Certain Block

Symptoms:

• Syncing stops at specific block height
• Logs show repeated import attempts

Solutions:

1. Check logs for errors:

tail -f /var/log/viction/node.log | grep -i error

2. Try rollback to previous block:

tomo --rollback <previous_block_hash>

3. Remove corrupted database and resync:

tomo removedb
tomo

Account Issues

Issue: “ErrLocked - password or unlock”

Error message:

Error: authentication needed: password or unlock

Cause: Account is locked and needs to be unlocked for signing

Solutions:

1. Unlock account when starting node:

tomo --unlock 0x1234... --password password.txt

2. Unlock via console:

tomo attach
> personal.unlockAccount("0x1234...", "password", 0)

Issue: “ErrDecrypt - could not decrypt key”

Error message:

Error: could not decrypt key with given passphrase

Cause: Wrong password for keystore file

Solutions:

1. Verify you’re using the correct password
2. Check if keystore file is corrupted:

cat ~/.ethereum/keystore/UTC--*
# Should show valid JSON

3. Restore from backup if corrupted

Issue: “ErrNoMatch - no key for given address”

Error message:

Error: no key for given address or file

Cause: Account address not found in keystore

Solutions:

1. List available accounts:

tomo account list

2. Check keystore directory:

ls -la ~/.ethereum/keystore/

3. Verify datadir path:

tomo account list --datadir /correct/path

4. Import missing key:

tomo account import keyfile.txt

Performance Issues

Issue: High CPU Usage

Symptoms:

• CPU at 100% constantly
• Node becomes unresponsive

Solutions:

1. Check what’s consuming CPU:

top -p $(pgrep tomo)

2. Reduce staker threads (for masternodes):

tomo --mine --miner.threads 1

3. Disable expensive metrics:

# Remove --metrics.expensive flag
tomo --metrics  # Without expensive flag

4. Check for attack (high RPC requests):

netstat -an | grep :8545 | wc -l

If high, restrict RPC access:

tomo --rpc --rpcaddr 127.0.0.1

Issue: High Memory Usage

Symptoms:

• Node using excessive RAM
• OOM killer terminates process

Solutions:

1. Check memory usage:

free -h
ps aux | grep tomo

2. Reduce cache size:

tomo --cache 1024  # Reduce to 1GB

3. Enable garbage collection:

GOGC=50 tomo  # More aggressive GC

4. Increase system swap:

sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Issue: Disk Space Full

Symptoms:

• Database write errors
• Node crashes with I/O errors

Solutions:

1. Check disk usage:

df -h
du -sh ~/.ethereum

2. Prune old data (if supported):

tomo --gcmode archive  # For archive node
tomo --gcmode full     # For full node (prunes old state)

3. Clean up logs:

sudo logrotate -f /etc/logrotate.d/viction

4. Move datadir to larger disk:

sudo systemctl stop viction
rsync -av ~/.ethereum/ /new/larger/disk/ethereum/
tomo --datadir /new/larger/disk/ethereum

RPC Issues

Issue: “Connection Refused”

Error message:

Error: connect ECONNREFUSED 127.0.0.1:8545

Cause: RPC server not running or not accessible

Solutions:

1. Enable RPC when starting:

tomo --rpc --rpcaddr 0.0.0.0 --rpcport 8545

2. Check if RPC port is listening:

netstat -tulpn | grep 8545

3. Check firewall:

sudo ufw status
sudo ufw allow 8545/tcp

Issue: “Method Not Allowed”

Error message:

Error: The method eth_sendTransaction is not available

Cause: Requested API method not enabled

Solutions:

1. Enable required APIs:

tomo --rpc --rpcapi "eth,net,web3,personal,admin"

Only enable APIs you need. Personal and admin APIs should not be exposed publicly.

Issue: “Too Many Requests”

Symptoms:

• RPC calls failing or timing out
• Slow response times

Solutions:

1. Implement rate limiting at reverse proxy level (nginx):

limit_req_zone $binary_remote_addr zone=rpc:10m rate=10r/s;

location / {
    limit_req zone=rpc burst=20;
    proxy_pass http://localhost:8545;
}

2. Increase timeout:

tomo --rpc --rpc.timeout 30

Network Issues

Issue: No Peers Connecting

Symptoms:

• Peer count stays at 0
• Node isolated from network

Solutions:

1. Check NAT settings:

tomo --nat extip:YOUR.PUBLIC.IP.ADDRESS

2. Manually add peers:

tomo attach
> admin.addPeer("enode://...@ip:port")

3. Configure static nodes in ~/.ethereum/static-nodes.json:

[
  "enode://pubkey@ip:30303"
]

4. Disable discovery temporarily:

tomo --nodiscover --bootnodes "enode://..."

Issue: Peers Keep Disconnecting

Symptoms:

• Peers connect then quickly disconnect
• Unstable peer count

Solutions:

1. Check network stability:

ping -c 100 8.8.8.8
mtr google.com

2. Check system time:

timedatectl status
# Ensure NTP is synchronized
sudo timedatectl set-ntp true

3. Increase max pending peers:

tomo --maxpendpeers 50

Masternode Issues

Issue: Not Signing Blocks

Symptoms:

• Registered masternode not producing blocks
• Missing assigned slots

Solutions:

1. Verify masternode registration:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_coinbase","params":[],"id":1}' \
  http://localhost:8545

2. Check account is unlocked:

tomo --unlock <masternode_address> --password password.txt

3. Verify staking is enabled:

tomo --mine --miner.threads 1

4. Check logs for errors:

grep -i "mining\|seal" /var/log/viction/node.log

Issue: Masternode Penalties

Symptoms:

• Receiving penalties for missed blocks
• Rewards lower than expected

Solutions:

1. Ensure high uptime:

   • Use monitoring and auto-restart
   • Implement failover

2. Optimize performance:

   • Use SSD storage
   • Sufficient RAM (8GB+)
   • Good network connectivity

3. Monitor continuously:

watch -n 10 'curl -s -X POST -H "Content-Type: application/json" \
  --data '"'"'{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'"'"' \
  http://localhost:8545'

Database Issues

Issue: “Database Corruption”

Error message:

Fatal: Failed to open database: corrupted database

Solutions:

1. Try database repair (if available):

tomo db inspect
tomo db check

2. Remove and resync:

cp -r ~/.ethereum/keystore /tmp/keystore-backup
tomo removedb
cp -r /tmp/keystore-backup ~/.ethereum/keystore
tomo

3. Restore from snapshot:

# Download trusted snapshot
wget https://snapshot.viction.xyz/latest.tar.gz
tar -xzf latest.tar.gz -C ~/.ethereum/
tomo

Logging and Debugging

Enable Debug Logging

tomo --verbosity 5  # Maximum verbosity

Verbosity levels:

• 0: Silent
• 1: Error
• 2: Warn
• 3: Info (default)
• 4: Debug
• 5: Trace

Increase Log Detail for Specific Modules

tomo --vmodule "p2p=5,eth=4"

Debug Console

Attach to running node for interactive debugging:

tomo attach
> debug.verbosity(5)
> eth.syncing
> net.peerCount
> admin.peers

Getting Help

Collect Debug Information

When reporting issues, include:

1. Node version:

tomo version

2. System information:

uname -a
cat /etc/os-release

3. Recent logs:

tail -n 100 /var/log/viction/node.log

4. Configuration:

tomo dumpconfig

5. Node status:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://localhost:8545

Community Resources

• Viction Documentation
• GitHub Issues
• Viction Forum
• Discord Community
• Telegram

Emergency Procedures

For critical issues:

1. Stop the node gracefully:

kill -INT $(pgrep tomo)  # SIGINT for graceful shutdown

2. Backup critical data:

tar -czf emergency-backup-$(date +%Y%m%d).tar.gz ~/.ethereum/keystore

3. Check system health:

dmesg | tail
journalctl -xe

4. Contact support with all debug information