Now I See Web3

Error Decoder Guide

What Are Solidity Errors?

When a Solidity smart contract transaction fails, the EVM reverts the state changes and returns encoded revert data. This revert data contains information about why the transaction failed, but like calldata, it is encoded in a binary format that is not human-readable without decoding.

A typical raw revert data string looks like this:

0x08c379a00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001a4e6f7420656e6f75676820746f6b656e20616c6c6f77616e636500000000000000

The Error Decoder translates this into the readable message: Error: "Not enough token allowance". Understanding how to decode these errors is essential for debugging smart contract failures quickly and effectively.

Solidity Error Types

Solidity supports three categories of errors, each with a different encoding format:

  • Error(string) — The most common type. Triggered by require(condition, "message") or revert("message"). The revert data starts with the function selector 0x08c379a0, followed by the ABI-encoded string message.
  • Panic(uint256) — Triggered automatically by the Solidity compiler for internal errors such as arithmetic overflow, array out-of-bounds access, division by zero, or failed assertions. The revert data starts with 0x4e487b71, followed by a numeric panic code that identifies the specific type of error.
  • Custom Errors — Introduced in Solidity 0.8.4. Defined with the error keyword, custom errors are more gas-efficient than string errors and can carry structured data. They are ABI-encoded like function calls, using the first 4 bytes as an error selector.

Common Panic Codes

When you encounter a Panic(uint256) error, the numeric code tells you what went wrong:

  • 0x01 — Failed assertion (assert(false))
  • 0x11 — Arithmetic overflow or underflow
  • 0x12 — Division or modulo by zero
  • 0x21 — Enum conversion out of bounds
  • 0x31 — Pop on an empty array
  • 0x32 — Array index out of bounds
  • 0x41 — Out of memory (too much memory allocated)
  • 0x51 — Called an uninitialized internal function

How to Use the Error Decoder

Follow these steps to decode any Solidity revert error:

  • Step 1: Navigate to the Error Decoder page.
  • Step 2: Paste the raw revert data hex string into the input field. This is typically found in the transaction receipt or in the error output from your Ethereum node or block explorer.
  • Step 3: For custom errors that are not standard Error(string) or Panic(uint256), you may also paste the ABI fragment (the custom error definition from your contract) to enable decoding.
  • Step 4: Click decode. The tool will identify the error type and display the decoded message or structured data in a readable format.

Decoding Custom Errors

Custom errors require the contract's ABI to decode because their selectors are not stored in any universal registry. To decode a custom error, you have two options:

  • Paste the ABI fragment — If you have the contract ABI, paste the specific error definition. For example: error InsufficientBalance(uint256 available, uint256 required). The decoder will use this to match the 4-byte error selector and decode the parameters.
  • Use the full ABI — Paste the complete ABI JSON array and the decoder will automatically match the error selector against all error definitions.

Example: Decoding an ERC-20 InsufficientBalance Error

Consider an ERC-20 contract that uses a custom error for insufficient balance checks:

error InsufficientBalance(uint256 available, uint256 required);

When this error is triggered, the revert data looks like:

0xcf4791810000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000008ac7230489e800000

After pasting the revert data and the error ABI fragment into the Error Decoder, you will see:

  • Error name: InsufficientBalance
  • available: 1000000000000000000 (1 ETH in wei)
  • required: 160000000000000000000 (160 ETH in wei)

This immediately tells you that the account had only 1 ETH but the operation required 160 ETH.

Debugging Workflow

An effective workflow for debugging a failed transaction using the Error Decoder:

  • Step 1 — Get the revert data: Find the failed transaction on a block explorer (Etherscan, for example) and copy the revert data from the transaction details. Alternatively, use the Transaction Analyzer on this site to find both the revert data and the decoded calldata in one place.
  • Step 2 — Identify the error type: Paste the revert data into the Error Decoder. If it starts with 0x08c379a0 or 0x4e487b71, the tool decodes it automatically.
  • Step 3 — For custom errors, provide the ABI: If the error selector does not match a known standard, paste the relevant ABI fragment. Check the contract's verified source code on the block explorer to find the error definition.
  • Step 4 — Interpret the result: Use the decoded error name and parameters to understand the exact condition that caused the failure. This is usually enough to pinpoint the bug or misconfigured parameter.