Documentation for eth_defi.revert_reason.fetch_transaction_revert_reason function.

fetch_transaction_revert_reason(web3, tx_hash, use_archive_node=False, unknown_error_message='<could not extract the revert reason>')[source]

Gets a transaction revert reason.

Ethereum nodes do not store the transaction failure reason in any database or index.

There is two ways to get the revert reason

  • Replay the transaction against the same block, and the same EVM state, where it was mined. An archive node is needed.

  • Replay the transaction against the current state. No archive node is needed, but the revert reason might be wrong.

To make this work

  • Live node must have had enough archive state for the replay to success (full nodes store only 128 blocks by default)

  • Ganache must have been started with block_time >= 1 so that transactions do not revert on transaction broadcast

  • When sending transsaction using web3.eth.send_transaction it must have gas set, or the transaction will revert during the gas estimation


receipts = wait_transactions_to_complete(web3, [tx_hash])

# Check that the transaction reverted
assert len(receipts) == 1
receipt = receipts[tx_hash]
assert receipt.status == 0

reason = fetch_transaction_revert_reason(web3, tx_hash)
assert reason == "VM Exception while processing transaction: revert BEP20: transfer amount exceeds balance"


use_archive_node=True path cannot be tested in unit testing.

Different JSON-RPC providers may return payloads and this function needs to handle each provider as a special case. See manual_bnb_chain_check_revert_reason.py for testing. Currently tested:

  • Ethereum Tester

  • Ganache

  • BNB Chain + geth

  • web3 (web3.main.Web3) – Our JSON-RPC connection

  • tx_hash (Union[hexbytes.main.HexBytes, str]) – Transaction hash of which reason we extract by simulation.

  • use_archive_node – Look up exact reason by running the tx against the past state. This only works if you are connected to the archive node.

  • unknown_error_message – Return this message if the revert reason extraction fails. Check the logs for details and pointers.


The revert reason of the placeholder message if we could not extract the reason somehow.

Return type