Troubleshooting/Developer FAQ
Having trouble with Hyperlane? Let's help you figure it out!
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!
Message Delivery
For a simple approach to debugging messages, try the Hyperlane Explorer. It can diagnose common issues with message delivery. See Debugging with Explorer for details.
Still need more help? Find our team on the Hyperlane Discord and ask away!
Can I retry my messages?
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).
Etherscan says an Error ocurrred
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 this one, know that your message has actually been processed.
I deployed Hyperlane to a new chain but my message/tokens are not getting delivered
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.
Message cancellation
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.
Off-chain Agents
Missing name field error
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.
Last updated
