Errors API Reference

If you use NPM, install the @chainlink/contracts-ccip NPM package.

For lanes where "Out of Order Execution" property is set to Optional or Required (see the CCIP Directory): Use version 1.5.0:

npm install @chainlink/contracts-ccip@1.5.0

For lanes where "Out of Order Execution" property is not set (see the CCIP Directory): Use version 1.4.0:

npm install @chainlink/contracts-ccip@1.4.0

If you use Yarn, install the @chainlink/contracts-ccip NPM package.

For lanes where "Out of Order Execution" property is set to Optional or Required (see the CCIP Directory): Use version 1.5.0:

yarn add @chainlink/contracts-ccip@1.5.0

For lanes where "Out of Order Execution" property is not set (see the CCIP Directory): Use version 1.4.0:

yarn add @chainlink/contracts-ccip@1.4.0

If you use Foundry, install the relevant release based on your environment.

For lanes where "Out of Order Execution" property is set to Optional or Required (see the CCIP Directory): Install version 5c711214167b7e6f05cf6de74bdab9f6e26763b2:

forge install smartcontractkit/ccip@5c711214167b7e6f05cf6de74bdab9f6e26763b2

For lanes where "Out of Order Execution" property is not set (see the CCIP Directory): Install version b06a3c2eecb9892ec6f76a015624413fffa1a122:

forge install smartcontractkit/ccip@b06a3c2eecb9892ec6f76a015624413fffa1a122

When invoking the ccipSend function, it is possible to encounter various errors. These might be thrown either by the CCIP router or by one of the downstream contracts called by the CCIP router. Below is a compiled list of potential errors you might encounter. Referencing this list will enable you to capture and handle these exceptions gracefully.

Router

Error	Parameters	Error Selector	Description
UnsupportedDestinationChain	uint64 destChainSelector	`0xae236d9c`	Thrown when the destination chain is not supported.
InsufficientFeeTokenAmount	-	`0x07da6ee6`	Thrown when the CCIP fees are paid with native tokens, but not enough is sent with the transaction.
InvalidMsgValue	-	`0x1841b4e1`	Thrown when the CCIP fees are not paid in native tokens, but `msg.value` is non-zero.

Onramp

Error	Parameters	Error Selector	Description
CannotSendZeroTokens	-	`0x5cf04449`	Thrown when the user tries to send a zero amount of tokens.
InvalidAddress	bytes encodedAddress	`0x370d875f`	Thrown when the receiver address is invalid.
InvalidChainSelector	uint64 chainSelector	`0xd9a9cd68`	Thrown when an invalid destination chain selector is used.
InvalidExtraArgsTag	-	`0x5247fdce`	Thrown when an invalid extra arguments tag is used.
MaxFeeBalanceReached	-	`0xe5c7a491`	Thrown when the onRamp has reached its maximum fee storage capacity. If it is full, it cannot process new transactions.
MessageGasLimitTooHigh	-	`0x4c4fc93a`	Thrown when the gas limit is too high.
MessageTooLarge	uint256 maxSize uint256 actualSize	`0x86933789`	Thrown when the message size exceeds the maximum allowed size.
MustBeCalledByRouter	-	`0x1c0a3529`	This error should never be thrown as the router always makes the call.
NotAFeeToken	address token	`0xa7499d20`	Thrown when an unsupported fee token is used.
RouterMustSetOriginalSender	-	`0xa4ec7479`	This error should never be thrown as the router always sets the sender.
SenderNotAllowed	address sender	`0xd0d25976`	Thrown when the sender is not allowlisted.
UnsupportedNumberOfTokens	-	`0x4c056b6a`	Thrown when too many tokens are involved in the transfer.
UnsupportedToken	IERC20 token	`0xbf16aab6`	Thrown when an unsupported transfer token is used.

RateLimiter

Error	Parameters	Error Selector	Description
AggregateValueMaxCapacityExceeded	uint256 capacity uint256 requested	`0xf94ebcd1`	Thrown when the user requests to transfer more value than the capacity of the aggregate rate limit bucket.
AggregateValueRateLimitReached	uint256 minWaitInSeconds uint256 available	`0x15279c08`	Thrown when the user requests to transfer more value than currently available in the bucket. The user might have to wait for at least `minWaitInSeconds` for enough availability or transfer the currently `available` amount.
BucketOverfilled	-	`0x9725942a`	This error should never be thrown as it indicates an invalid bucket state.
PriceNotFoundForToken	address token	`0x9a655f7b`	Thrown when a price cannot be found for a specific token.
TokenMaxCapacityExceeded	uint256 capacity uint256 requested address tokenAddress	`0x1a76572a`	Thrown when the user requests to transfer more of a token than the capacity of the bucket.
TokenRateLimitReached	uint256 minWaitInSeconds uint256 available address tokenAddress	`0xd0c8d23a`	Thrown when the user requests to transfer more of a token than currently available in the bucket. The user might have to wait at least `minWaitInSeconds` for enough availability, or transfer the currently `available` amount.

ERC20

Error	Description
ERC20: burn amount exceeds balance	Thrown when the amount to be burned exceeds the pool balance.
ERC20: transfer amount exceeds allowance	Thrown when the transfer amount exceeds the allowance.

PriceRegistry

Error	Parameters	Error Selector	Description
ChainNotSupported	uint64 chain	`0x2e59db3a`	Thrown when a chain is not supported.
StaleGasPrice	uint64 destChainSelector uint256 threshold uint256 timePassed	`0xf08bcb3e`	Thrown when the gas price is stale.
TokenNotSupported	address token	`0x06439c6b`	Thrown when a token is not supported.
StaleTokenPrice	address token uint256 threshold uint256 timePassed	`0xc65fdfca`	Thrown when the price of a token is stale.