All SDK errors extend CCIPError with a machine-readable code, structured context, and isTransient flag. For handling patterns, retries, and contract error parsing, see Error Handling.
Chain and Network
| Error | Code | When Thrown | Recovery |
|---|
CCIPChainNotFoundError | CHAIN_NOT_FOUND | Chain selector/ID not in supported networks | Verify chain is supported by CCIP |
CCIPChainFamilyUnsupportedError | CHAIN_FAMILY_UNSUPPORTED | Chain family not implemented | Use supported chain family (EVM, Solana, Aptos, Sui, TON) |
CCIPChainFamilyMismatchError | CHAIN_FAMILY_MISMATCH | Operation across incompatible chain families | Ensure source/dest chains are compatible |
CCIPRpcNotFoundError | RPC_NOT_FOUND | No RPC endpoint configured | Provide RPC URL |
Transaction and Block
All transient — wait and retry.
| Error | Code | When Thrown | Recovery |
|---|
CCIPTransactionNotFoundError | TRANSACTION_NOT_FOUND | Transaction hash doesn't exist | Verify hash, wait for confirmation |
CCIPBlockNotFoundError | BLOCK_NOT_FOUND | Block doesn't exist or not finalized | Wait for block finalization |
CCIPTransactionNotFinalizedError | TRANSACTION_NOT_FINALIZED | Transaction not yet finalized | Wait for finality |
Message
| Error | Code | Transient | When Thrown | Recovery |
|---|
CCIPMessageNotFoundInTxError | MESSAGE_NOT_FOUND_IN_TX | No | Transaction has no CCIP messages | Verify correct transaction hash |
CCIPMessageIdNotFoundError | MESSAGE_ID_NOT_FOUND | Yes | Message ID not found in search | Provide OnRamp hint, expand search range |
CCIPMessageDecodeError | MESSAGE_DECODE_FAILED | No | Failed to decode message data | Check message format compatibility |
CCIPMessageBatchIncompleteError | MESSAGE_BATCH_INCOMPLETE | Yes | Not all messages in batch found | Retry with larger search range |
CCIPMessageNotInBatchError | MESSAGE_NOT_IN_BATCH | No | Message not found in commit batch | Verify message ID and sequence number range |
CCIPMessageNotVerifiedYetError | MESSAGE_NOT_VERIFIED_YET | Yes | Message not yet verified by off-chain system | Wait and retry (retryAfterMs: 15000) |
CCIPMessageInvalidError | MESSAGE_INVALID | No | Message structure is invalid | Verify message fields |
Lane and Routing
| Error | Code | When Thrown | Recovery |
|---|
CCIPOffRampNotFoundError | OFFRAMP_NOT_FOUND | No OffRamp for source→dest lane | Verify lane exists on CCIP |
CCIPLaneNotFoundError | LANE_NOT_FOUND | Lane doesn't exist | Check CCIP lane configuration |
CCIPOnRampRequiredError | ONRAMP_REQUIRED | OnRamp address needed but not provided | Provide OnRamp address |
Commit and Merkle
| Error | Code | Transient | When Thrown | Recovery |
|---|
CCIPCommitNotFoundError | COMMIT_NOT_FOUND | Yes | Message not yet committed | Wait for DON to commit |
CCIPMerkleRootMismatchError | MERKLE_ROOT_MISMATCH | No | Calculated root doesn't match committed root | Verify all messages in batch are included |
CCIPMerkleProofEmptyError | MERKLE_PROOF_EMPTY | No | No proof elements | Check message inclusion |
CCIPMerkleTreeEmptyError | MERKLE_TREE_EMPTY | No | No messages to hash | Verify batch contains messages |
Token
| Error | Code | When Thrown | Recovery |
|---|
CCIPTokenNotFoundError | TOKEN_NOT_FOUND | Token address invalid or not found | Verify token address |
CCIPTokenNotConfiguredError | TOKEN_NOT_CONFIGURED | Token not configured in registry | Check TokenAdminRegistry |
CCIPTokenNotInRegistryError | TOKEN_NOT_IN_REGISTRY | Token not in admin registry | Register token with CCIP |
CCIPTokenDecimalsInsufficientError | TOKEN_DECIMALS_INSUFFICIENT | Token decimals too low for transfer | Use different token or adjust amount |
CCIPTokenPoolChainConfigNotFoundError | TOKEN_REMOTE_NOT_CONFIGURED | Remote chain not configured for token | Configure remote chain in pool |
Execution
| Error | Code | When Thrown | Recovery |
|---|
CCIPExecTxRevertedError | EXEC_TX_REVERTED | Manual execution transaction reverted | Check gas limit, receiver contract |
CCIPExecTxNotConfirmedError | EXEC_TX_NOT_CONFIRMED | Execution tx didn't confirm | Increase gas, retry |
CCIPReceiptNotFoundError | RECEIPT_NOT_FOUND | Execution receipt not found | Wait for execution, check OffRamp |
Attestation (USDC / LBTC)
All transient — wait and retry.
| Error | Code | When Thrown | Recovery |
|---|
CCIPUsdcAttestationError | USDC_ATTESTATION_FAILED | USDC attestation service error | Retry after delay |
CCIPLbtcAttestationError | LBTC_ATTESTATION_ERROR | LBTC attestation service error | Retry after delay |
CCIPLbtcAttestationNotFoundError | LBTC_ATTESTATION_NOT_FOUND | LBTC attestation not yet available | Wait and retry |
CCIPLbtcAttestationNotApprovedError | LBTC_ATTESTATION_NOT_APPROVED | LBTC attestation pending approval | Wait and retry (retryAfterMs: 30000) |
Wallet and Signer
| Error | Code | When Thrown | Recovery |
|---|
CCIPWalletInvalidError | WALLET_INVALID | Wallet not a valid signer | Provide ethers Signer or use viemWallet(client) |
CCIPWalletNotSignerError | WALLET_NOT_SIGNER | Wallet can't sign transactions | Use wallet with signing capability |
CCIPInsufficientBalanceError | INSUFFICIENT_BALANCE | Insufficient funds for transaction | Add funds to wallet |
Version
| Error | Code | When Thrown | Recovery |
|---|
CCIPVersionUnsupportedError | VERSION_UNSUPPORTED | CCIP version not supported | Use supported version (v1.2, v1.5, v1.6) |
CCIPVersionFeatureUnavailableError | VERSION_FEATURE_UNAVAILABLE | Feature not available in version | Upgrade to newer CCIP version |
CCIPHasherVersionUnsupportedError | HASHER_VERSION_UNSUPPORTED | Hasher not implemented for version | Use supported version |
HTTP and API
| Error | Code | Transient | When Thrown | Recovery |
|---|
CCIPHttpError | HTTP_ERROR | Yes | HTTP request failed | Retry with backoff |
CCIPTimeoutError | TIMEOUT | Yes | Operation timed out | Increase timeout, retry |
CCIPApiClientNotAvailableError | API_CLIENT_NOT_AVAILABLE | No | API client disabled (apiClient: null) | Use RPC-based methods or enable API |
Solana-Specific
| Error | Code | When Thrown | Recovery |
|---|
CCIPSolanaComputeUnitsExceededError | SOLANA_COMPUTE_UNITS_EXCEEDED | Transaction exceeded compute units | Increase compute units in extraArgs |
CCIPSolanaLookupTableNotFoundError | SOLANA_LOOKUP_TABLE_NOT_FOUND | Address lookup table not found | Verify router configuration |
CCIPSplTokenInvalidError | TOKEN_INVALID_SPL | Invalid SPL token | Verify token is valid SPL token |
Aptos-Specific
| Error | Code | When Thrown | Recovery |
|---|
CCIPAptosAddressInvalidError | ADDRESS_INVALID_APTOS | Invalid Aptos address format | Use valid Aptos address |
CCIPAptosExtraArgsV2RequiredError | EXTRA_ARGS_APTOS_V2_REQUIRED | EVMExtraArgsV2 required for Aptos | Use EVMExtraArgsV2 with allowOutOfOrderExecution |
Viem Adapter
| Error | Code | When Thrown | Recovery |
|---|
CCIPViemAdapterError | VIEM_ADAPTER_ERROR | Viem client misconfigured | Ensure chain and account are defined on client |
Transient Error Codes
These error codes have isTransient: true and may succeed on retry:
| Code | Default Retry Delay |
|---|
BLOCK_NOT_FOUND | 12s |
BLOCK_TIME_NOT_FOUND | 12s |
TRANSACTION_NOT_FOUND | 5s |
TRANSACTION_NOT_FINALIZED | 5s |
MESSAGE_ID_NOT_FOUND | 30s |
MESSAGE_BATCH_INCOMPLETE | 5s |
MESSAGE_NOT_VERIFIED_YET | 15s |
COMMIT_NOT_FOUND | 60s |
RECEIPT_NOT_FOUND | 5s |
USDC_ATTESTATION_FAILED | 30s |
LBTC_ATTESTATION_ERROR | 30s |
LBTC_ATTESTATION_NOT_FOUND | 30s |
LBTC_ATTESTATION_NOT_APPROVED | 30s |
HTTP_ERROR | 5s |
TIMEOUT | 5s |
SOLANA_LOOKUP_TABLE_NOT_FOUND | 5s |
SOLANA_REF_ADDRESSES_NOT_FOUND | 5s |
Use getRetryDelay(error) to get the appropriate delay for a specific error instance (respects retryAfterMs hints).