06e48ef34b
- Add infrastructure.md and workflow files to .gitignore to prevent sensitive info leaks - Change blockchain node mempool backend default from memory to database for persistence - Refactor blockchain node logger with StructuredLogFormatter and AuditLogger (consistent with coordinator) - Add structured logging fields: service, module, function, line number - Unify coordinator config with Database
2.4 KiB
2.4 KiB
Troubleshooting
Common issues and solutions for blockchain nodes.
Common Issues
Node Won't Start
# Check logs
tail -f ~/.aitbc/logs/chain.log
# Common causes:
# - Port already in use
# - Corrupted database
# - Invalid configuration
Solutions:
# Kill existing process
sudo lsof -i :8080
sudo kill $(sudo lsof -t -i :8080)
# Reset database
rm -rf ~/.aitbc/data/chain.db
aitbc-chain init
# Validate config
aitbc-chain validate-config
Sync Stuck
# Check sync status
aitbc-chain sync-status
# Force sync from scratch
aitbc-chain reset --hard
# Check peer connectivity
aitbc-chain p2p connections
Solutions:
# Add more peers
aitbc-chain p2p add-bootstrap /dns4/new-peer.example.com/tcp/7070/p2p/...
# Clear peer database
rm -rf ~/.aitbc/data/peers.db
# Restart with fresh sync
aitbc-chain start --sync-mode full
P2P Connection Issues
# Check connectivity
aitbc-chain p2p check-connectivity
# Test port forwarding
curl http://localhost:8080/rpc/net_info
Solutions:
# Open firewall
sudo ufw allow 7070/tcp
sudo ufw allow 8080/tcp
# Check NAT configuration
aitbc-chain p2p nat-status
# Use relay mode
aitbc-chain start --p2p-relay-enabled
High Memory Usage
# Check memory usage
htop | grep aitbc-chain
# Check database size
du -sh ~/.aitbc/data/
Solutions:
# Prune old data
aitbc-chain prune --keep-blocks 10000
# Reduce peer count
# Edit config: max_peers: 25
# Enable compression
aitbc-chain start --db-compression
RPC Not Responding
# Check RPC status
curl http://localhost:8080/rpc/health
# Check if RPC is enabled
aitbc-chain status | grep RPC
Solutions:
# Restart with RPC enabled
aitbc-chain start --rpc-enabled
# Check CORS settings
# Edit config: rpc.cors_origins
# Increase rate limits
# Edit config: rpc.rate_limit: 2000
Diagnostic Commands
# Full system check
aitbc-chain doctor
# Network diagnostics
aitbc-chain diagnose network
# Database diagnostics
aitbc-chain diagnose database
# Log analysis
aitbc-chain logs --analyze
Getting Help
# Generate debug report
aitbc-chain debug-report > debug.txt
# Share on Discord or GitHub Issues
Next
- Quick Start — Get started
- Configuration - Configure your node
- Operations — Day-to-day ops