Solidity Error Handling: Require, Assert, and Revert

Hello! Welcome to the first lesson in our module on Advanced Solidity & Contract Logic.

In the previous module, we built a complete workflow: writing, compiling, and deploying a simple smart contract using Hardhat. However, those contracts were a bit too trusting—they assumed all inputs would be correct and everything would work as planned. As a backend developer, you know that robust applications must anticipate and handle errors gracefully.

Today, we'll address this by learning how to handle contract errors and revert transactions using require, assert, and revert. This is one of the most critical aspects of smart contract development. Unlike traditional backend systems where you might log an error and continue, errors in smart contracts have unique and powerful consequences, revolving around the core blockchain principles of atomicity and state reversion.

Atomicity and State Reversion: The Blockchain's Safety Net

Before we dive into the specific functions, we must understand what happens when a function call fails on the blockchain.

When a transaction encounters an error, the Ethereum Virtual Machine (EVM) performs a revert. This means:

1. Execution Halts: The function immediately stops running.
2. State Changes Are Undone: Any changes made to state variables during the transaction are completely rolled back, as if the transaction never happened.
3. Gas is Consumed: The gas used up to the point of the error is consumed and paid to the validator. The remaining gas is returned to the caller.

This process ensures atomicity: a transaction either completes successfully and all its state changes are saved, or it fails and has no effect on the contract's state. This is a fundamental security feature that prevents contracts from being left in a corrupt or inconsistent state.

Now, let's learn how to trigger these reverts intentionally to protect our contracts.

The Three Pillars of Error Handling in Solidity

Solidity provides three primary mechanisms for error handling: require, revert, and assert. We'll also look at a modern, gas-efficient feature called "custom errors".

1. require(): The Gatekeeper for Inputs and Permissions

The require function is your primary tool for validation. You should use it to enforce conditions on inputs from users and other contracts, or to check for required state conditions before a function runs.

Use require to validate:

• Inputs: Is an input value within an acceptable range?
• Permissions: Is msg.sender the owner of the contract?
• State: Does the contract have enough funds to perform an action?

The syntax is require(condition, "Error message");. If the condition evaluates to false, the transaction reverts, and the optional error message string is returned to the caller.

Here's a common example for access control:

address public owner;

constructor() {
    owner = msg.sender;
}

function withdraw() public {
    // Only the owner can call this function.
    require(msg.sender == owner, "Caller is not the owner");
    
    // ... logic to withdraw funds
}

2. revert(): For Complex Conditional Logic

The revert statement does the same thing as require: it stops execution and reverts state changes. However, it's used when the validation logic is more complex and doesn't fit neatly into a single require condition. You typically see it inside if/else blocks.

Example of revert in an if block:

if (msg.sender != owner) {
    revert("Caller is not the owner");
}

Custom Errors: The Modern, Gas-Efficient Way

Since Solidity version 0.8.4, you can define custom errors. These are much more gas-efficient than using string messages, especially if the message is long or used frequently. This is now the recommended best practice.

1. Declare the error: error NotOwner();
2. Use it with revert: if (msg.sender != owner) { revert NotOwner(); }

You can also pass data into your custom errors, which is useful for debugging.
error InsufficientBalance(uint currentBalance, uint required);
revert InsufficientBalance(address(this).balance, amount);

3. assert(): The Bug Detector

The assert function is fundamentally different from require. It should only be used to test for internal errors and to check conditions that should never, ever be false. These are often called "invariants".

A failed assert indicates a bug in your contract logic.

Use assert to check for:

• Arithmetic overflow/underflow (though this is built-in since Solidity 0.8.0).
• Conditions that should be logically impossible.
• Invariants (e.g., ensuring a contract's balance didn't change unexpectedly).

If an assert fails, it reverts the transaction. In older Solidity versions, it consumed all remaining gas, but now it behaves more like require in that regard. The key difference is semantic: a failed require means the user did something wrong; a failed assert means the developer did something wrong.

Deeper Dive: Error vs. Panic

Modern Solidity makes the distinction between require and assert even clearer by having them generate different types of errors:

• require(false, ...) generates an Error(string) error.
• assert(false) generates a Panic(uint256) error.

This distinction is useful for off-chain tools and for contracts that might try/catch these errors (a more advanced topic). For now, the important thing to remember is the semantic difference:

• Error (from require): For runtime errors related to external inputs or conditions.
• Panic (from assert): For internal, "impossible" errors indicating a bug.

Summary: require vs. revert vs. assert

Let's consolidate what we've learned. The choice between these functions depends on why an error might occur.

Here is a quick summary table:

contract VendingMachine {
    mapping(address => uint) public snackBalances;
    uint public totalSnacksInMachine = 100;

    function buySnacks(uint amount) public {
        // 1. Use 'require' for input validation.
        // The user controls the 'amount', so we must validate it.
        require(amount > 0, "Cannot buy zero snacks.");
        require(amount <= totalSnacksInMachine, "Not enough snacks in the machine.");

        uint initialUserBalance = snackBalances[msg.sender];

        // Perform the state changes
        totalSnacksInMachine -= amount;
        snackBalances[msg.sender] += amount;

        // 2. Use 'assert' to check for an invariant.
        // This condition should be logically impossible to fail if the code above is correct.
        // A failure here indicates a bug (like an overflow/underflow in older Solidity versions).
        assert(snackBalances[msg.sender] == initialUserBalance + amount);
    }
}

Conclusion

You've now learned the fundamental techniques for building robust and secure smart contracts. By correctly using require, revert, and assert, you can protect your contract from invalid data and prevent it from ever entering an inconsistent state.

Key Takeaways:

• Errors in Solidity trigger a revert, which undoes all state changes in the transaction, ensuring atomicity.
• require is your primary tool for validating user inputs and permissions. Think of it as a gatekeeper.
• revert (often with custom errors) is a flexible way to trigger errors from within complex conditional logic.
• assert is a sanity check for your own code. It verifies invariants—conditions that should never be false. A failed assert points to a bug.

Preview of the Next Lesson:
In the exercise above, you saw a mapping. This is a powerful data structure we haven't formally covered yet. In our next lesson, we will dive into mappings, learning how to use them to create efficient key-value data structures. This is essential for tracking data like the token balances of different users in the cryptocurrency we are aiming to build.