proxmox/docs/09-troubleshooting/TROUBLESHOOTING_GUIDE.md

Comprehensive Troubleshooting Guide

Purpose: Common issues and solutions for bridge operations

---

❌ Common Errors

"Execution reverted"

Cause: Transaction reverted by contract logic

Solutions:

1. Check contract state
2. Verify parameters
3. Check allowances
4. Verify balances

Debug:

cast call <CONTRACT> "<function>" <args> --rpc-url $RPC_URL

---

"Insufficient funds"

Cause: Not enough ETH for gas or LINK for fees

Solutions:

1. Check ETH balance

   cast balance <address> --rpc-url $RPC_URL
   

2. Check LINK balance

   cast call <LINK_TOKEN> "balanceOf(address)" <address> --rpc-url $RPC_URL
   

3. Add funds if needed

---

"Nonce too low"

Cause: Transaction nonce is lower than current nonce

Solutions:

1. Check current nonce

   cast nonce <address> --rpc-url $RPC_URL
   

2. Wait for pending transactions

3. Use correct nonce

---

"Replacement transaction underpriced"

Cause: Pending transaction with lower gas price

Solutions:

1. Wait for pending transaction
2. Use higher gas price
3. Cancel pending transaction (if possible)

---

"Destination not enabled"

Cause: Destination chain not configured on bridge

Solutions:

1. Verify destination configuration

   cast call <BRIDGE> "destinations(uint64)" <SELECTOR> --rpc-url $RPC_URL
   

2. Configure destination if missing

   bash scripts/configure-bridge-destinations.sh
   

---

"Gas price below minimum"

Cause: Gas price too low for network

Solutions:

1. Get current gas price

   cast gas-price --rpc-url $RPC_URL
   

2. Use higher gas price (1.2x-1.5x current)

   bash scripts/bridge-with-dynamic-gas.sh
   

---

🔍 Debugging Steps

1. Check System Status

bash scripts/health-check.sh

2. Check Transaction Status

cast tx <tx_hash> --rpc-url $RPC_URL

3. Check Logs

tail -100 logs/alerts-$(date +%Y%m%d).log

4. Run Test Suite

bash scripts/test-suite.sh all

5. Check Recent Events

bash scripts/monitor-bridge-transfers.sh

---

🛠️ Advanced Troubleshooting

Transaction Stuck

1. Check transaction status
2. Check nonce
3. Retry with higher gas
4. Consider canceling if possible

Contract Not Found

1. Verify contract address
2. Check network
3. Verify contract deployment

RPC Issues

1. Test RPC connectivity
2. Check RPC logs
3. Try backup RPC endpoint

---

Last Updated: $(date)