Debugging Failed Messages

Debug failed or stuck CCIP messages in three steps: track status, diagnose the error, and manually execute.

Step	Command	Purpose
1. Track	ccip-cli show	Check message status and identify failures
2. Diagnose	ccip-cli parse	Decode error data
3. Execute	ccip-cli manual-exec	Retry with corrected parameters

You need RPC endpoints for both source and destination chains. For manual execution, you also need a wallet. See Configuration.

Step 1: Track the Message

Bash

ccip-cli show 0xSourceTxHash

You can also pass a message ID (32-byte hex) instead of a tx hash. See show command reference.

Message States

State	Description	Action
UNTOUCHED	Committed, not yet executed	Wait or manual execute
IN_PROGRESS	Execution in progress	Wait
SUCCESS	Executed successfully	None
FAILURE	Execution failed	Diagnose and retry

If the state is FAILURE, the output includes Return Data — hex-encoded error bytes you can decode in Step 2.

If the state is UNTOUCHED after a long time, possible causes:

• The DON hasn't executed it yet (wait longer)
• An earlier message from the same sender failed (sender nonce ordering) — execute each failed message in order
• Rate limiter exhausted

Step 2: Diagnose the Failure

Decode the Return Data from Step 1:

Bash

ccip-cli parse 0x08c379a0000000000000000000000000...

Common Errors

Error	Cause	Fix
Empty return data or Panic: 0x11	Receiver exceeded gas limit	Increase gas with --gas-limit or --estimate-gas-limit
UnsupportedToken(address)	Token not registered on this lane	Verify with get-supported-tokens
Error: "..." (custom string)	Receiver contract logic failed	Fix the receiver contract, then re-execute

Step 3: Manual Execution

Execute the message with corrected parameters:

Bash

ccip-cli manual-exec 0xSourceTxHash --wallet ledger

Or by message ID (only needs destination chain RPC):

Bash

ccip-cli manual-exec 0xMessageId --wallet ledger

With Gas Override

Bash

# Explicit gas limit
ccip-cli manual-exec 0xSourceTxHash --gas-limit 500000 --wallet ledger

# Auto-estimate with 20% margin
ccip-cli manual-exec 0xSourceTxHash --estimate-gas-limit 20 --wallet ledger

Ordering Issues

CCIP enforces sender nonce ordering. If an earlier message failed, later messages from the same sender are blocked. Execute each failed message in order:

Bash

ccip-cli manual-exec 0xFirstFailedTx --wallet ledger
ccip-cli manual-exec 0xSecondFailedTx --wallet ledger

Solana

Solana transactions have size limits. For large messages:

Bash

ccip-cli manual-exec 0xTxHash \
  --force-buffer \
  --force-lookup-table \
  --wallet ledger

Use --clear-leftover-accounts to clean up from a previous failed attempt.

See the manual-exec command reference for all options.

Verify

After manual execution, confirm the message succeeded:

Bash

ccip-cli show 0xSourceTxHash

The state should now be SUCCESS.

Related

• show — Command reference
• parse — Command reference
• manual-exec — Command reference
• Troubleshooting — Common errors and solutions