Custom Errors in Solidity: Lower Gas, Cleaner Code

Solidity 0.8.4 introduced custom errors. They are a direct replacement for require statements with string messages. The benefit is straightforward: lower gas costs, both at deployment and at runtime.

This post explains how custom errors work, how much gas they save and why, and how to migrate existing contracts to use them.

The Problem with String Errors

The traditional pattern for error handling in Solidity looks like this:

 1contract OldWayErrors {
 2    address public owner;
 3
 4    constructor() {
 5        owner = msg.sender;
 6    }
 7
 8    function restrictedFunction() public view {
 9        require(msg.sender == owner, "Only owner can call this function");
10    }
11}

Every string you pass to require gets embedded in the contract bytecode. The longer the string, the more bytes are stored on-chain. This affects deployment cost directly. Multiply that across a contract with 10 or 20 functions, each with one or more require checks, and the bytecode bloat becomes significant.

At runtime, reverting with a string message means the EVM must ABI-encode that string and return it as revert data. That encoding costs gas on every failed transaction.

How Custom Errors Work

A custom error is declared at the contract level using the error keyword. When a condition fails, you use revert with that error instead of require.

 1contract NewWayErrors {
 2    address public owner;
 3
 4    error Unauthorized();
 5
 6    constructor() {
 7        owner = msg.sender;
 8    }
 9
10    function restrictedFunction() public view {
11        if (msg.sender != owner) {
12            revert Unauthorized();
13        }
14    }
15}

Under the hood, Solidity hashes the error signature (for example, Unauthorized()) and takes the first 4 bytes. This is the same mechanism used for function selectors. When the transaction reverts, those 4 bytes are returned as the revert data instead of an encoded string.

4 bytes versus dozens or hundreds of bytes per error. That is where the savings come from.

Gas Savings: Deployment

Consider a contract with several common validation checks:

 1contract TraditionalErrors {
 2    mapping(address => uint256) public balances;
 3
 4    function transfer(address to, uint256 amount) public {
 5        require(to != address(0), "Cannot transfer to zero address");
 6        require(balances[msg.sender] >= amount, "Insufficient balance");
 7        require(amount > 0, "Amount must be greater than zero");
 8
 9        balances[msg.sender] -= amount;
10        balances[to] += amount;
11    }
12}

Those three strings total around 80 characters. Each character is one byte in the bytecode. In a real contract with many functions, this adds up fast.

Now the same logic with custom errors:

 1contract ModernErrors {
 2    mapping(address => uint256) public balances;
 3
 4    error ZeroAddress();
 5    error InsufficientBalance();
 6    error InvalidAmount();
 7
 8    function transfer(address to, uint256 amount) public {
 9        if (to == address(0)) revert ZeroAddress();
10        if (balances[msg.sender] < amount) revert InsufficientBalance();
11        if (amount == 0) revert InvalidAmount();
12
13        balances[msg.sender] -= amount;
14        balances[to] += amount;
15    }
16}

Each error declaration contributes only a 4-byte selector to the bytecode. You can also reuse the same error in multiple functions without duplicating anything. Across a full contract, the deployment cost reduction typically falls between 5,000 and 15,000 gas depending on how many string messages you had and how long they were.

Gas Savings: Runtime

When a transaction reverts, the EVM returns revert data to the caller. With a string message, that data includes the full ABI-encoded string. With a custom error, it is just the 4-byte selector.

The runtime saving per revert is smaller than the deployment saving, typically 20 to 50 gas. But for a protocol processing a high volume of transactions where a percentage of them revert (failed transfers, access control checks, slippage limits), that saving compounds across every failed call over the contract's lifetime.

Adding Parameters to Custom Errors

Custom errors support parameters. This lets you include useful context in a revert without the overhead of string formatting.

 1contract AdvancedErrors {
 2    mapping(address => uint256) public balances;
 3
 4    error InsufficientBalance(uint256 available, uint256 required);
 5    error TransferFailed(address from, address to, uint256 amount);
 6
 7    function transfer(address to, uint256 amount) public {
 8        uint256 balance = balances[msg.sender];
 9
10        if (balance < amount) {
11            revert InsufficientBalance(balance, amount);
12        }
13
14        balances[msg.sender] -= amount;
15        balances[to] += amount;
16    }
17}

The parameters are ABI-encoded and included in the revert data. The base cost is still lower than a string revert, because you avoid the fixed overhead of encoding a string type. And the error is more precise: a caller or interface can decode the exact values that caused the failure.

Adding parameters does increase the revert data size compared to a parameter-less custom error. The savings compared to an equivalent require with a formatted string are still present, but smaller. For the tightest gas optimisation, prefer parameter-less errors on hot paths.

Organising Errors in a Real Contract

For contracts with many error cases, group errors by category at the top of the contract:

 1contract TokenWithErrors {
 2    // Access control
 3    error Unauthorized();
 4    error NotOwner();
 5
 6    // Transfer validation
 7    error ZeroAddress();
 8    error InsufficientBalance(uint256 available, uint256 required);
 9    error TransferToSelf();
10
11    // Contract state
12    error ContractPaused();
13    error AlreadyInitialized();
14
15    // ... implementation
16}

This makes the error surface of a contract easy to read at a glance. Tools like Etherscan decode custom errors automatically, so users and developers still get meaningful information when a transaction fails. The 4-byte selector maps back to the human-readable error name in any ABI-aware tool.

A function with multiple checks reads cleanly with the if-revert pattern:

 1function complexOperation(address target, uint256 value) public {
 2    if (target == address(0)) revert ZeroAddress();
 3    if (msg.sender != owner) revert Unauthorized();
 4    if (paused) revert ContractPaused();
 5    if (value > maxValue) revert InvalidAmount();
 6
 7    // operation logic
 8}

Testing Custom Errors

In Foundry, use vm.expectRevert with the error selector:

1function testUnauthorizedAccess() public {
2    vm.expectRevert(Unauthorized.selector);
3    myContract.restrictedFunction();
4}

For errors with parameters, encode the full expected revert data:

 1function testInsufficientBalance() public {
 2    vm.expectRevert(
 3        abi.encodeWithSelector(
 4            MyContract.InsufficientBalance.selector,
 5            0,   // available
 6            100  // required
 7        )
 8    );
 9    myContract.transfer(recipient, 100);
10}

In Hardhat with Ethers.js, you can match against the error name directly using .revertedWithCustomError():

1await expect(
2    contract.restrictedFunction()
3).to.be.revertedWithCustomError(contract, "Unauthorized");

Compatibility

Custom errors require Solidity 0.8.4 or later. If your project still targets an earlier compiler version, you cannot use them. Most active projects have moved past 0.8.4, so this is rarely a blocker in practice.

Hardhat, Foundry, and Ethers.js all support custom error decoding. Block explorers handle them correctly. The toolchain support is solid.

One thing to be aware of: if your contract inherits from external libraries or interfaces that still use require with strings, those strings will still appear in the bytecode from those dependencies. Custom errors only replace the errors you write yourself.

Migration Strategy

If you have an existing contract you want to convert, prioritise the highest-value changes first:

1. Identify functions that are called frequently or that revert often (access control checks, balance checks, slippage guards).
2. Replace those require statements first.
3. Add parameters to errors where the caller or a frontend needs the failed values to handle the revert properly.
4. Replace the remaining require statements for consistency.

There is no need to convert everything at once. A contract can mix require strings and custom errors. The two approaches are compatible at the bytecode level.

Summary

Custom errors are a simple, low-effort optimisation with real impact. Deployment costs drop because string bytecode is replaced by 4-byte selectors. Runtime costs drop because revert data is smaller. Code clarity improves because error names are precise and reusable across functions.

The pattern is well-supported across the Solidity toolchain and has become standard practice in modern contract development. If you are writing new contracts or have the opportunity to audit existing ones, switching to custom errors is one of the easiest improvements you can make.