Troubleshooting Guide

This guide helps you diagnose and resolve common issues with ChainLaunch.

Common Issues

Node Won't Start

Symptoms:

• Node status remains "Stopped" after clicking start
• Error message in logs

Diagnosis:

1. Check node logs: Go to the nodes list, and enter the node that is failing. Then at the bottom check the logs.

2. Check system resources:

   • Verify CPU and memory available
   • Check disk space: df -h

3. Check port availability:

   # Linux/macOS
   lsof -i :30303  # P2P port
   lsof -i :8545   # JSON-RPC port

Solutions:

Nodes Not Discovering Each Other

Symptoms:

• Block height not increasing
• Peer count = 0
• Consensus not starting (Fabric/Besu)

Diagnosis:

1. Check peer count:

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

2. Check network connectivity between nodes:

   # Test if node A can reach node B
   ping node-b-ip
   telnet node-b-ip 30303

3. Check enode URLs (Besu):

   # Get node's enode
   curl -X POST http://localhost:8545 \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "method": "admin_nodeInfo",
       "params": [],
       "id": 1
     }'

Solutions:

Backup Issues

Symptoms:

• Backup job fails with "connection refused" or "access denied"
• Scheduled backups not running
• Restore operation fails

Diagnosis:

1. Check backup target configuration:

   curl http://localhost:8100/api/v1/backups/targets

2. Verify S3 connectivity:

   # Test S3 access with AWS CLI
   aws s3 ls s3://your-backup-bucket/

3. Check backup status:

   curl http://localhost:8100/api/v1/backups

Solutions:

Monitoring Issues

Symptoms:

• Prometheus metrics endpoint not responding
• Grafana dashboards show "No data"
• Node metrics not updating

Diagnosis:

1. Check if monitoring is enabled:

   curl http://localhost:8100/api/v1/settings

2. Test the Prometheus metrics endpoint directly:

   curl http://localhost:9090/metrics

3. Verify node metrics are exposed:

   # For Besu nodes
   curl http://localhost:9545/metrics
    
   # For Fabric peers
   curl http://localhost:9443/metrics

Solutions:

Authentication Issues

Symptoms:

• Login returns 401 Unauthorized
• Session expires unexpectedly
• API key not accepted

Diagnosis:

1. Test authentication:

   # Basic auth
   curl -u admin:password http://localhost:8100/api/v1/nodes
    
   # API key
   curl -H "X-API-Key: clpro_..." http://localhost:8100/api/v1/nodes

2. Check server logs for auth errors: Look for authentication failed or token expired messages in the ChainLaunch server logs.

Solutions:

Besu Node Issues

Symptoms:

• Besu validator not producing blocks
• Consensus stalled across the network
• Peers not connecting to the network

Diagnosis:

1. Check peer count:

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

2. Check sync status:

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

3. Check latest block number:

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

4. Check node status via ChainLaunch API:

   curl http://localhost:8100/api/v1/nodes

Solutions:

Fabric-X Issues

Fabric-X has a few platform-specific failure modes that don't apply to classic Fabric. The Fabric-X Quickstart troubleshooting table covers the most common ones; here's the summary:

For deeper Fabric-X diagnostics see Fabric-X Architecture (port layout and component data flow) and Fabric-X Monitoring (Prometheus /metrics endpoints per role).

See Also

• API Reference
• RBAC & Permissions
• Audit Logging
• Getting Started