Troubleshooting | Chainlink

ChainlinkNetworkNotConfiguredException
You called router/isChainSupported or router/getFee for a network with no matching entry under Chainlink:NetworkRpcUrls.
Fix: Add Chainlink:NetworkRpcUrls:{network} pointing at a working RPC endpoint for that network — see Configuration. Every other operation on this node works without any RPC URL configured at all.

"is not a valid EVM address" (ArgumentException)
A receiverAddress, feeToken, or tokenAmounts[].token value passed to message/build or router/getFee isn't exactly 0x + 40 hex characters.
Fix: Double-check the address wasn't truncated or copy-pasted with extra whitespace/characters. This node validates address shape itself before ABI-encoding, specifically because Nethereum's own encoder silently accepts a too-short address with no error — catching it here, loudly, is intentional. See CCIP Concepts.

"tokenAmounts entry has an invalid 'amount' value"
A tokenAmounts[].amount entry wasn't a valid non-negative integer string — commonly caused by writing a bare JSON number (1000) instead of a quoted string ("1000"), or including a decimal point (token amounts are wei-denominated integers, not decimal token units).
Fix: Quote every amount as a string, and convert to the token's smallest unit (e.g. multiply by 10^18 for an 18-decimal token) before passing it in.

MESSAGE_NOT_FOUND
message/getStatus (or checkManualExecutionRequired, which calls it internally) returned 404 for the given messageId.
Fix: Confirm the message ID is the exact value returned by the on-chain ccipSend transaction receipt, not a transaction hash — they are different values. Also allow a short delay after sending; very recently sent messages may not be indexed yet.

CCIP_API_RATE_LIMITED
The CCIP API returned 429 after this node's own retry budget (3 attempts, honoring Retry-After with exponential backoff otherwise) was exhausted.
Fix: Reduce polling frequency, or configure a CCIP API key (see Configuration) — an API key raises rate-limit headroom on the public endpoints even though it isn't required to use them.

CCIP_API_UPSTREAM_ERROR
The CCIP API returned 500/502/503/504. These are also retried automatically up to 3 times before surfacing.
Fix: Usually transient — retry the workflow step. If persistent, check Chainlink's own CCIP status page before assuming a problem in your configuration.

Router address is a placeholder / on-chain read reverts unexpectedly
router/getAddress/convertChainSelector read from a bundled static reference table where only Ethereum mainnet's chain selector was independently confirmed — every Router address, and every non-Ethereum-mainnet row, is a representative placeholder (see Networks).
Fix: Reconcile the address you're relying on against the live CCIP Directory before trusting it beyond simple connectivity testing.

Attempting to actually send a message, or manually re-execute a failed one
This node never sends a CCIP message (message/build only prepares one) and cannot itself submit a manual execution for a FAILURE-state message.
Fix: Use the Ethereum ExecutionNode's contract-write step to actually call ccipSend(...), and use the CCIP Explorer for manual re-execution until this node's own support for it ships — see Roadmap.

Attempting a Data Feeds, VRF, Automation, or Functions operation
This node implements CCIP only. There is no resource value on this node for price feeds, randomness, upkeep automation, or off-chain compute.
Fix: For Data Feeds, use the Ethereum ExecutionNode's generic contract-call step plus the Standards Registry. VRF/Automation/Functions are not implemented by any node in this codebase yet.