Troubleshooting Failed Messages

Failures can occur at various stages. Here’s how to troubleshoot:

Failure: Transaction Reverted on Source Chain

Symptom: Your attempt to call submitMessage() on the source Gateway contract fails immediately or reverts.

Diagnosis:

• Check the transaction on the source chain's explorer.
• Look for the revert reason provided by the Gateway contract. Common reasons include:
  • insufficient tx value: You haven't sent enough native currency to cover the estimated gas costs for Timechain processing and destination execution.
  • msg data too large: Your message payload exceeds MAX_PAYLOAD_SIZE.
  • invalid gmp network: The destination network ID is not supported or misconfigured.

Remedy:

• Adjust the msg.value sent with submitMessage based on estimateMessageCost
• Reduce the size of your message data.
• Verify the destination network ID is correct and supported.

Failure: Message Submitted but Not Processed by Timechain

Symptom: GmpCreated event is visible on the source chain, but the Message ID doesn't appear on the Timechain Explorer after a reasonable period, or its status remains CREATED for too long.

Diagnosis:

• Confirm Source Chain Finality: Ensure your source chain transaction is deeply finalized.
• Check Chronicle Node Status: The "Chronicles" pane on the Explorer can give clues.
• Explorer Data Lag: The Explorer itself might have a slight delay in indexing.

Remedy:

• Wait for sufficient finality on the source chain.
• If consistently delayed, check Analog's Discord  for reported issues with Chronicle nodes or the specific source chain integration.

Failure: Message Stuck or Failed During Timechain Processing

Symptom: Message appears on Timechain Explorer, but status is stuck (e.g., MESSAGE_RECEIVED, PROCESSING).

Diagnosis:

• Timechain Explorer:
  • Look for linked Task IDs in the message details.
  • Search for these Task IDs on the Explorer.
• Shard Status: Check the "Shards" pane on the Explorer. If the relevant shard is offline, message processing might be stalled.

Remedy:

• If a shard is offline, the system is designed for fault tolerance; however, significant shard outages could still cause delays. Check Analog's Discord  for reported issues.

Failure: Execution Failed on Destination Chain

Symptom: Timechain Explorer shows the message status as MESSAGE_EXECUTED but indicates a failure (or FAILED), or the GmpExecuted event on the destination chain shows status = REVERT.

Diagnosis:

• Destination Gateway GmpExecuted Event: This is the most direct source of information.
  • id: Matches your GMP Message ID.
  • status: Will be REVERT (or equivalent enum for failure).
  • result: May contain an error message or a hash of the error data from the execution attempt.
• Destination Gateway Contract Logs/Trace:
  • Check the transaction hash on the destination chain's explorer.
  • Examine internal calls or revert reasons from the Gateway's _execute function. Common issues:
    • insufficient gas to execute GMP message: The executionGasLimit set in the original submitMessage was too low for the actual execution on the destination chain (including the Gateway's overhead and the call to your onGmpReceived function).
    • Target Contract Revert: Your IGmpReceiver::OnGmpReceived function (or any contract it calls) reverted. The result field from GmpExecuted or the transaction trace on the destination explorer should provide the specific revert reason from your contract.

Remedy:

• Insufficient Gas: Resubmit the message from the source chain with a higher executionGasLimit.
• Target Contract Revert: Debug your destination contract's OnGmpReceived logic. Ensure it can handle the incoming data format, has enough gas internally, and doesn't violate any conditions. The result from GmpExecuted is key here.