# Comprehensive Troubleshooting Guide

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

**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**:
```bash
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
   ```bash
   cast balance <address> --rpc-url $RPC_URL
   ```

2. Check LINK balance
   ```bash
   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
   ```bash
   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
   ```bash
   cast call <BRIDGE> "destinations(uint64)" <SELECTOR> --rpc-url $RPC_URL
   ```

2. Configure destination if missing
   ```bash
   bash scripts/configure-bridge-destinations.sh
   ```

---

### "Gas price below minimum"

**Cause**: Gas price too low for network

**Solutions**:
1. Get current gas price
   ```bash
   cast gas-price --rpc-url $RPC_URL
   ```

2. Use higher gas price (1.2x-1.5x current)
   ```bash
   bash scripts/bridge-with-dynamic-gas.sh
   ```

---

## 🔍 Debugging Steps

### 1. Check System Status
```bash
bash scripts/health-check.sh
```

### 2. Check Transaction Status
```bash
cast tx <tx_hash> --rpc-url $RPC_URL
```

### 3. Check Logs
```bash
tail -100 logs/alerts-$(date +%Y%m%d).log
```

### 4. Run Test Suite
```bash
bash scripts/test-suite.sh all
```

### 5. Check Recent Events
```bash
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)