LogoLogo
  • ⏩Introduction
    • Hyperlane Introduction
    • Getting started
    • Why Should You Use Hyperlane?
  • Permissionless Interoperability
    • Overview
    • Deploy Hyperlane
    • Warp Routes
      • Deploy a Warp Route
      • Deploy a UI for your Warp Route
    • Modular Rollup Interoperability
  • Build With Hyperlane
    • Quickstarts
      • Messaging
      • Accounts
      • Queries
      • hyperlane-quickstart repo
    • Guides
      • Finding my messages
      • Automatically pay for interchain gas
      • Manually pay for interchain gas
      • Choosing an interchain gas paymaster contract
      • Unit testing
      • Specifying an ISM
      • V2 migration guide
    • Explorer
      • Debugging messages
      • Configuring PI Chains
      • REST API
      • GraphQL API
    • Troubleshooting/Developer FAQ
    • Example apps
  • APIs and SDKs
    • Messaging API
      • Send
      • Receive
    • Accounts API
    • Queries API
    • Warp Route API
    • Interchain gas paymaster API
    • Hyperlane App Framework
      • Example usage
        • HelloWorld
        • Interchain Token
      • Solidity SDK
        • HyperlaneConnectionClient
        • Router
      • NodeJS SDK
        • RPC Providers
        • Deployment
        • Interchain testing
        • Quoting gas payments
        • App Abstraction
    • Hooks API
      • Contract addresses
  • Protocol
    • Overview
    • Mailbox
    • Interchain security modules
      • Interface
      • Multisig ISM
      • Routing ISM
      • Aggregation ISM
      • Optimistic ISM
      • Wormhole ISM
      • Hook ISM
      • CCIP-Read ISM
    • Interchain gas payments
    • Staking and slashing
    • Agents
      • Validators
      • Relayers
      • Watchtowers
    • Warp Routes
    • Implementation Guide
  • Operators
    • Validators
      • Guide
      • AWS setup
      • Monitoring and alerting
    • Relayers
      • Guide
      • Message filtering
    • Agent keys
      • Hexadecimal keys
      • AWS KMS keys
    • Agent configuration
      • Configuration reference
    • Running with docker compose
  • Resources
    • FAQ
    • Glossary
    • Contract addresses
      • Permissionless Deployment Contract Addresses
    • Domain identifiers
      • Permissionless Domain Identifiers
    • Default ISM settings
    • Coming Soon: Hyperlane v3
    • Token sources & faucets
    • Latencies
    • Github
    • Discord
    • Website
Powered by GitBook
On this page
  • Message Delivery
  • Message cancellation
  • Off-chain Agents
  1. Build With Hyperlane

Troubleshooting/Developer FAQ

Having trouble with Hyperlane? Let's help you figure it out!

PreviousGraphQL APINextExample apps

Last updated 1 year ago

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 for details.

Still need more help? Find our team on the 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 , 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.

Debugging with Explorer
Hyperlane Discord
this one
This is actually fine!
This is also fine!