smom-dbis-138/docs/operations/integrations/CCIP_TROUBLESHOOTING.md

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

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

Check Message Status

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

Check LINK Balance

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

Calculate Fee

# 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

# 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

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

Emergency Pause

If critical issues occur:

// 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 Router Setup
• CCIP Message Format
• CCIP Fees
• Chainlink CCIP Support