Custom Errors

A custom error is a user-defined type declared with the error keyword, used with the revert statement. It provides a structured, low-cost alternative to require(condition, "description").

• Declaration: error InsufficientBalance(uint256 available, uint256 required);
• Usage: if (balance < amount) revert InsufficientBalance(balance, amount);
• Gas Efficiency: Consumes significantly less gas than equivalent string error messages, as the error signature (4-byte selector) is stored on-chain, not the full string.

Custom errors are deployed for input validation, state checks, and access control where clarity and gas optimization are critical.

• Gas Savings: The primary driver for adoption; reverting with a custom error costs ~90% less gas than an equivalent error string.
• Improved Debugging: Provides structured data (parameters) in transaction revert traces, making failures easier to diagnose off-chain.
• Contract Upgrades: Error types can be added in later versions without breaking existing integrations that only check for revert conditions.

Leading DeFi and infrastructure projects have widely adopted custom errors for core contract logic.

• Uniswap V4: Uses custom errors like InvalidPool, LockFailure, and CurrencyNotSettled throughout its hook and pool management system.
• OpenZeppelin Contracts: Libraries like @openzeppelin/contracts use errors such as ERC20InsufficientBalance and OwnableUnauthorizedAccount.
• Compound Finance & Aave: Implement errors for interest rate model calculations and liquidity checks to minimize gas costs for users.

Ecosystem tooling has evolved to parse and display custom errors for developers and end-users.

• Ethers.js & Viem: These libraries decode custom error selectors and parameters from failed transactions, presenting them in human-readable form.
• Hardhat & Foundry: Testing frameworks have built-in support for expecting specific custom error reverts in unit tests (e.g., vm.expectRevert).
• Block Explorers: Etherscan and others decode and display custom error names and arguments in transaction receipts.

Custom errors differ fundamentally from older Solidity error-handling methods.

• vs. require(condition, "string"): Custom errors are cheaper on deployment and runtime because the string data is not stored in bytecode. They also allow parameterized data.
• vs. assert(condition): assert is for internal invariants and consumes all remaining gas on failure, while custom errors (used with revert) refund remaining gas.
• Error Signature: A custom error is identified by its 4-byte selector (first 4 bytes of keccak256("ErrorName(type)")), which is logged in the transaction receipt.

Effective use of custom errors involves careful naming and parameter design.

• Descriptive Naming: Use names like Unauthorized, InvalidInput, or Overflow that clearly indicate the failure mode.
• Parameter Selection: Include relevant state variables or arguments (e.g., uint256 actualValue, address caller) to aid off-chain debugging.
• Security Consideration: The error type and parameters are not stored on-chain after the transaction; they are only emitted in the revert reason. Do not rely on them for on-chain logic.
• Backwards Compatibility: Interfaces or abstract contracts should declare expected custom errors to guide integrators.

While custom errors save significant gas compared to require statements with string messages, they can obscure debugging. Off-chain tools must map the 4-byte selector (e.g., 0x12345678) back to the error name. Ensure your development and monitoring stack supports this mapping for effective incident response.

• Gas Savings: Reverts with custom errors cost ~~50-100 gas, versus ~20,000+ gas for revert strings.
• Tooling Dependency: Debugging requires the contract's ABI or source code to decode the error.

Custom errors can inadvertently expose sensitive contract state or business logic. The error parameters are visible on-chain in the revert data.

• Example Risk: Reverting with InsufficientBalance(userBalance, requiredAmount) publicly reveals a user's balance.
• Best Practice: Use generic error types for access control failures (e.g., Unauthorized()) and avoid passing private data as parameters.

Define a clear and consistent error hierarchy to prevent ambiguity and improve maintainability. Group related errors within libraries or inherited contracts.

• Library Pattern: Define common errors in a base library (e.g., Errors.sol) using error InsufficientAllowance();.
• Inheritance: Child contracts can use parent contract errors, ensuring uniform error signatures across the system.
• Naming Convention: Use descriptive, verb-noun names like TransferFailed, InvalidSignature.

Thoroughly test custom error reverts. Since they do not return strings, standard assertion methods in testing frameworks need to be adapted to check for specific error selectors.

• Foundry Example: Use vm.expectRevert(MyContract.CustomError.selector);.
• Hardhat Example: Catch the revert and decode the data using the contract interface.
• Coverage: Ensure test suites validate all possible error conditions and that the correct error type is thrown.

Adding, removing, or changing custom errors is a breaking change for interfaces and upgrades. The 4-byte selector is derived from the error name and parameter types.

• Breaking Change: Modifying an error's signature will change its selector, breaking off-chain integrations that listen for it.
• Upgrade Strategy: For upgradeable contracts, consider errors as part of the public API. New errors should be additive where possible.

Ensure your application frontend and monitoring services (like Chainscore) can properly interpret custom errors. This requires the ABI to be available for decoding transaction revert reasons.

• User Feedback: Map error selectors to user-friendly messages in your UI.
• Analytics: Monitoring dashboards should decode and categorize failures by error type to track the health of specific contract functions.
• Documentation: Publicly document all custom errors and their meanings for integrators.

These are the three built-in error handling functions in Solidity that custom errors replace or augment.

• require(condition, "message"): Validates inputs and state, refunds gas, and reverts with a string message.
• assert(condition): Checks for internal invariants; consumes all gas on failure.
• revert("message"): Unconditionally reverts with a string message. Custom errors are used with revert CustomError() for a more gas-efficient and type-safe alternative to string messages.

A primary motivation for using custom errors. Deploying and executing a contract with custom errors is significantly cheaper.

• Deployment Cost: Error strings are stored in contract bytecode, while custom error signatures are only 4 bytes.
• Execution Cost: Reverting with revert CustomError() costs ~100 gas, versus ~2,000+ gas for a revert with a descriptive string. This makes custom errors a critical tool for minimizing transaction fees and optimizing contract efficiency.

The technical identifier for a custom error.

• Signature: The canonical form, e.g., InsufficientBalance(uint256,uint256).
• Selector: The first 4 bytes of the Keccak-256 hash of the signature (e.g., 0xcf479181). This selector is what the EVM uses to identify the error in revert data. Off-chain tools and clients decode the revert data using the Application Binary Interface (ABI) to map the selector back to the human-readable error name and parameters.

The process that enables custom errors to be understood.

• On-chain: When a custom error is reverted, its parameters are ABI-encoded into the revert return data.
• Off-chain: Clients (like Ethers.js or Web3.py) use the contract's ABI to decode this data, reconstructing the error type and its values for developers and users. Without the correct ABI, a custom error appears as an opaque, generic revert.

A control structure introduced in Solidity 0.6.0 that allows a contract to handle failures from external calls. Custom errors integrate with this system.

• Catching Errors: A catch block can be defined to specifically catch a revert CustomError() from the external call, allowing for graceful failure handling within the contract logic.
• Example: try otherContract.action() catch (CustomError memory err) { ... }. This enables more complex and resilient contract interactions.

A set of standardized error codes used by the assert() function and certain invalid operations, defined in EIP-140.

• Examples: 0x01 for assert failure, 0x11 for arithmetic overflow.
• Contrast with Custom Errors: Panic errors are generic, built-in VM failures. Custom errors (using revert) are user-defined, descriptive, and intended for expected failure conditions. They represent different categories of contract failure.