Troubleshooting/Developer FAQ
Having trouble with Hyperlane? Let's help you figure it out!
Last updated
Having trouble with Hyperlane? Let's help you figure it out!
Last updated
As you navigate the interchain space and begin sending your first messages between blockchains, you may run into some issues. This section will help you troubleshoot common issues so you can get right back on the Interchain Highway and onwards to your destination!
For a simple approach to debugging messages, try the Hyperlane Explorer. It can diagnose common issues with message delivery. See for details.
Still need more help? Find our team on the and ask away!
Relayers are configured to automatically retry delivering a message with an exponential back-off (assuming that there was sufficient gas paid for on the origin chain).
More often than not, it is not actually an error. What happens is that the Mailbox will attempt to make a call to the recipient to query its Interchain security modules. If a recipient does not specify an ISM by implementing the interface, the Mailbox will default to the default ISM that is configured on it. However, to Etherscan, the transaction trace includes a revert which it calls out, however in this case, it is a false-positive. So if you see a process transaction like , know that your message has actually been processed.
The relayer logs are your best friend. If you are running a validator on your local machine and writing checkpoints to localStorage, make sure that the relayer has access to them. If you use docker, ensure that you mount the path through. Also, enable the --allowLocalCheckpointSyncers option on the relayer.
Once a message is enqueued on a Mailbox merkle tree, from the system perspective, messages are perpetually processable. If messages are supposed to be of limited validity or cancelable, it is up to the application to encode those semantics into their message bytes.
An error about a missing name field most likely indicates that you have an environment variable that implies the existence of a chain, but said chain does not exist in the config files. You may have misspelled the ENV name (HYP_BASE_CHAINS_GOERLI_CONNECTION_URL). Or you may have specified a new chain but forgot to load the corresponding config file.
