Build / Integration Guide / Troubleshooting

9. Troubleshooting

🐛 Common Issues and Solutions

Sync Issues

# Check node sync status
grpcurl -plaintext localhost:18142 tari.rpc.BaseNode/GetSyncInfo

# Check tip info
grpcurl -plaintext localhost:18142 tari.rpc.BaseNode/GetTipInfo

# Check connected peers
grpcurl -plaintext localhost:18142 tari.rpc.BaseNode/ListConnectedPeers

# Common fixes for sync issues:
# 1. Restart services: docker-compose restart
# 2. Clear peer ban list: rm ~/.tari/mainnet/peer_db/banned_peers
# 3. Manual peer addition: Use SetBaseNode RPC call

Connectivity

# Verify the gRPC port is listening locally
ss -tlnp | grep 18142

# Test raw TCP connectivity to a peer
nc -zv PLACEHOLDER_peer_address 18141

# Check firewall rules aren't blocking required ports
sudo ufw status | grep -E "18141|18142|18143"

# Check DNS/Tor resolution if using hidden services
torsocks curl -s https://check.torproject.org | grep -i congratulations

# Common fixes:
# 1. Open firewall ports: sudo ufw allow 18141/tcp
# 2. Restart Tor if using hidden service transport: sudo systemctl restart tor
# 3. Verify NAT/port forwarding on routers for self-hosted nodes

Transactions

# Check the status of a specific transaction
grpcurl -plaintext -d '{"transaction_ids": ["PLACEHOLDER_tx_id"]}' 
  localhost:18143 tari.rpc.Wallet/GetTransactionInfo

# List recent completed transactions
grpcurl -plaintext localhost:18143 tari.rpc.Wallet/GetCompletedTransactions

# Check for stuck/pending transactions
grpcurl -plaintext localhost:18143 tari.rpc.Wallet/GetPendingTransactions

# Common fixes:
# 1. A transaction stuck as "pending" usually means it hasn't been mined yet - verify on a
#    block explorer using the transaction's excess signature
# 2. If a payment ID isn't matching, confirm it was passed as raw bytes, not double-encoded
# 3. Re-broadcast a stuck transaction: wallet cancel-transaction then resubmit

Performance

# Check base node resource usage
top -b -n 1 | grep minotari_node

# Check disk I/O - blockchain sync is I/O heavy
iostat -x 1 5

# Check database size and growth rate
du -sh ~/.tari/mainnet/data/base_node

# Check gRPC request latency
time grpcurl -plaintext localhost:18142 tari.rpc.BaseNode/GetTipInfo

# Common fixes:
# 1. Move blockchain data to an NVMe SSD if on spinning disk or network storage
# 2. Increase the node's connection pool size in config.toml if gRPC calls are queuing
# 3. Add a read replica / additional read-only wallet if monitoring load is high