# CCIP Troubleshooting Guide

## Common Issues

### Message Not Received

**Symptoms**: Message sent but not received on target chain

**Diagnosis**:
1. Check message was sent successfully
2. Verify target chain selector is correct
3. Check receiver contract address
4. Verify CCIP Router is operational
5. Check LINK balance for fees

**Solutions**:
- Verify transaction hash on source chain
- Check CCIP Router logs
- Verify receiver contract is deployed
- Ensure sufficient LINK tokens
- Check target chain status

### High Fees

**Symptoms**: Fees are unexpectedly high

**Diagnosis**:
1. Check message size
2. Monitor gas prices on target chain
3. Verify fee calculation
4. Check for network congestion

**Solutions**:
- Reduce message size
- Wait for lower gas prices
- Optimize message encoding
- Consider batching updates

### Replay Protection Errors

**Symptoms**: "Message already processed" error

**Diagnosis**:
1. Check `processedMessages` mapping
2. Verify message IDs are unique
3. Check for duplicate sends

**Solutions**:
- Ensure message IDs are unique
- Clear processed messages (if safe)
- Check for duplicate transaction sends
- Verify replay protection logic

### Router Not Found

**Symptoms**: "Router not found" or "Invalid router address"

**Diagnosis**:
1. Verify router address is correct
2. Check router is deployed
3. Verify network/chain ID matches

**Solutions**:
- Update router address in contracts
- Deploy router if missing
- Verify chain ID configuration
- Check router deployment status

### Insufficient LINK

**Symptoms**: "Insufficient LINK balance" error

**Diagnosis**:
1. Check LINK token balance
2. Verify token address is correct
3. Check approval for spending

**Solutions**:
- Transfer more LINK tokens
- Verify LINK token address
- Approve contract to spend LINK
- Check token contract is correct

### Message Encoding Errors

**Symptoms**: "Invalid message format" or decode failures

**Diagnosis**:
1. Check message encoding format
2. Verify data types match
3. Check for encoding errors

**Solutions**:
- Verify encoding matches expected format
- Check data types are correct
- Test encoding/decoding separately
- Review message structure

### Target Chain Unavailable

**Symptoms**: Message fails to deliver, router unavailable

**Diagnosis**:
1. Check target chain status
2. Verify router is operational
3. Check network connectivity

**Solutions**:
- Wait for chain to recover
- Check router health status
- Verify network connectivity
- Contact support if persistent

## Diagnostic Commands

### Check Router Status

```bash
# Check router is accessible
cast call $CCIP_ROUTER "getSupportedTokens(uint64)" $CHAIN_SELECTOR --rpc-url $RPC_URL
```

### Check Message Status

```bash
# Check if message was processed
cast call $RECEIVER "processedMessages(bytes32)" $MESSAGE_ID --rpc-url $RPC_URL
```

### Check LINK Balance

```bash
# Check LINK balance
cast call $LINK_TOKEN "balanceOf(address)" $SENDER_CONTRACT --rpc-url $RPC_URL
```

### Calculate Fee

```bash
# Calculate fee for message
cast call $SENDER "calculateFee(uint64,bytes)" $CHAIN_SELECTOR $MESSAGE_DATA --rpc-url $RPC_URL
```

## Monitoring

### Key Metrics

- Message send success rate
- Message delivery latency
- Fee consumption
- Error rates
- Router availability

### Alerts

Set up alerts for:
- High error rates
- Low success rates
- High fees
- Router unavailability
- Low LINK balance

## Logs

### Check Contract Logs

```bash
# Get recent events
cast logs --from-block latest-100 --address $SENDER_CONTRACT --rpc-url $RPC_URL
```

### Check Router Logs

Check CCIP Router service logs for errors.

## Recovery Procedures

### Resend Failed Message

1. Verify original message failed
2. Check why it failed
3. Fix underlying issue
4. Resend message with new message ID

### Clear Processed Messages

**Warning**: Only if safe to do so

```solidity
// Admin function to clear processed messages (use with caution)
function clearProcessedMessage(bytes32 messageId) external onlyAdmin {
    delete processedMessages[messageId];
}
```

### Emergency Pause

If critical issues occur:

```solidity
// Pause message sending
function pause() external onlyAdmin {
    paused = true;
    emit Paused();
}
```

## Getting Help

1. Check CCIP documentation
2. Review contract code
3. Check Chainlink status page
4. Contact Chainlink support
5. Review GitHub issues

## References

- [CCIP Integration Guide](CCIP_INTEGRATION.md)
- [CCIP Router Setup](CCIP_ROUTER_SETUP.md)
- [CCIP Message Format](CCIP_MESSAGE_FORMAT.md)
- [CCIP Fees](CCIP_FEES.md)
- [Chainlink CCIP Support](https://chain.link/support)