Troubleshooting

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:

Verify password file content:

cat password.txt

Try unlocking interactively:

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

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:

Check what’s using the port:

lsof -i :30303
netstat -tulpn | grep 30303

Stop the conflicting process or use a different port:

tomo --port 30304

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:

Check for running instances:

ps aux | grep tomo

Remove stale lock file:

rm ~/.ethereum/LOCK

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:

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:

Verify network connectivity:

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

Check firewall:

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

Try different bootnodes:

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

Clear peer database and restart:

tomo removedb
tomo

Issue: Slow Sync Speed

Symptoms:

Syncing takes extremely long time
Low block import rate

Solutions:

Use fast sync mode (if starting from scratch):

tomo --syncmode fast

Increase cache size:

tomo --cache 4096  # Increase cache to 4GB

Ensure sufficient resources:

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

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

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

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:

Check logs for errors:

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

Try rollback to previous block:

tomo --rollback <previous_block_hash>

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:

Unlock account when starting node:

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

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:

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

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

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:

List available accounts:

tomo account list

Check keystore directory:

ls -la ~/.ethereum/keystore/

Verify datadir path:

tomo account list --datadir /correct/path

Import missing key:

tomo account import keyfile.txt

Performance Issues

Issue: High CPU Usage

Symptoms:

CPU at 100% constantly
Node becomes unresponsive

Solutions:

Check what’s consuming CPU:

top -p $(pgrep tomo)

Reduce staker threads (for masternodes):

tomo --mine --miner.threads 1

Disable expensive metrics:

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

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:

Check memory usage:

free -h
ps aux | grep tomo

Reduce cache size:

tomo --cache 1024  # Reduce to 1GB

Enable garbage collection:

GOGC=50 tomo  # More aggressive GC

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:

Check disk usage:

df -h
du -sh ~/.ethereum

Prune old data (if supported):

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

Clean up logs:

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

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:

Enable RPC when starting:

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

Check if RPC port is listening:

netstat -tulpn | grep 8545

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:

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:

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;
}

Increase timeout:

tomo --rpc --rpc.timeout 30

Network Issues

Issue: No Peers Connecting

Symptoms:

Peer count stays at 0
Node isolated from network

Solutions:

Check NAT settings:

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

Manually add peers:

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

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

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

Disable discovery temporarily:

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

Issue: Peers Keep Disconnecting

Symptoms:

Peers connect then quickly disconnect
Unstable peer count

Solutions:

Check network stability:

ping -c 100 8.8.8.8
mtr google.com

Check system time:

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

Increase max pending peers:

tomo --maxpendpeers 50

Masternode Issues

Issue: Not Signing Blocks

Symptoms:

Registered masternode not producing blocks
Missing assigned slots

Solutions:

Verify masternode registration:

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

Check account is unlocked:

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

Verify staking is enabled:

tomo --mine --miner.threads 1

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:

Ensure high uptime:
- Use monitoring and auto-restart
- Implement failover
Optimize performance:
- Use SSD storage
- Sufficient RAM (8GB+)
- Good network connectivity
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:

Try database repair (if available):

tomo db inspect
tomo db check

Remove and resync:

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

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:

Node version:

tomo version

System information:

uname -a
cat /etc/os-release

Recent logs:

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

Configuration:

tomo dumpconfig

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

Emergency Procedures

For critical issues:

Stop the node gracefully:

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

Backup critical data:

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

Check system health:

dmesg | tail
journalctl -xe

Contact support with all debug information

Get Started

Core Concepts

Node Operations

Features

Development

Operations

​Overview

​Node Won’t Start

​Issue: “Fatal: Failed to unlock account”

​Issue: “Fatal: Error starting protocol stack”

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

​Sync Issues

​Issue: Node Not Syncing

​Issue: Slow Sync Speed

​Issue: Sync Stuck at Certain Block

​Account Issues

​Issue: “ErrLocked - password or unlock”

​Issue: “ErrDecrypt - could not decrypt key”

​Issue: “ErrNoMatch - no key for given address”

​Performance Issues

​Issue: High CPU Usage

​Issue: High Memory Usage

​Issue: Disk Space Full

​RPC Issues

​Issue: “Connection Refused”

​Issue: “Method Not Allowed”

​Issue: “Too Many Requests”

​Network Issues

​Issue: No Peers Connecting

​Issue: Peers Keep Disconnecting

​Masternode Issues

​Issue: Not Signing Blocks

​Issue: Masternode Penalties

​Database Issues

​Issue: “Database Corruption”

​Logging and Debugging

​Enable Debug Logging

​Increase Log Detail for Specific Modules

​Debug Console

​Getting Help

​Collect Debug Information

​Community Resources

​Emergency Procedures

Build docs developers (and LLMs) love

Overview

Node Won’t Start

Issue: “Fatal: Failed to unlock account”

Issue: “Fatal: Error starting protocol stack”

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

Sync Issues

Issue: Node Not Syncing

Issue: Slow Sync Speed

Issue: Sync Stuck at Certain Block

Account Issues

Issue: “ErrLocked - password or unlock”

Issue: “ErrDecrypt - could not decrypt key”

Issue: “ErrNoMatch - no key for given address”

Performance Issues

Issue: High CPU Usage

Issue: High Memory Usage

Issue: Disk Space Full

RPC Issues

Issue: “Connection Refused”

Issue: “Method Not Allowed”

Issue: “Too Many Requests”

Network Issues

Issue: No Peers Connecting

Issue: Peers Keep Disconnecting

Masternode Issues

Issue: Not Signing Blocks

Issue: Masternode Penalties

Database Issues

Issue: “Database Corruption”

Logging and Debugging

Enable Debug Logging

Increase Log Detail for Specific Modules

Debug Console

Getting Help

Collect Debug Information

Community Resources

Emergency Procedures