The Ultimate Guide to Debugging Smart Contracts: Tips and Tools for Web3 Developers

Photo by Tim Graf on Unsplash

The Ultimate Guide to Debugging Smart Contracts: Tips and Tools for Web3 Developers

Play this article

Smart contract development is vital to building decentralized applications on the blockchain. However, as with any software development, debugging smart contracts can be challenging but can quickly determine the cause of a single transaction or contract execution failure with an advanced tool for debugging Solidity smart contracts.

We can implement a suitable solution once we identify the error that led to a specific issue and learn in-depth details about the error's nature.

This guide will provide tips and tools for debugging smart contracts to help Web3 developers ensure their contracts work as intended.

D_D Newsletter CTA

Debugging Smart Contracts

Smart contract debugging is identifying and fixing errors in smart contracts. It is essential in developing any decentralized application as it ensures the contracts function as intended.

Contract development can run into several problems, including unpredictable behaviour, coding errors, and security flaws. Debugging can assist in resolving these problems and preventing more serious ones from developing later.

Implementation, testing, and deployment are only a few processes in developing a smart contract. A crucial phase in each of these steps is debugging. After deploying the contract, debugging helps find and correct flaws in the code introduced during the writing phase.

Debugging assists in finding and correcting issues that might have gone unnoticed during the writing stage during the testing phase. Debugging also ensures that the contract is deployed correctly and interacts with the blockchain as intended during deployment.

Debugging Tips

Writing smart contracts that are easy to debug is a crucial step in development. Below are some tips for writing smart contracts that are easy to debug:

  • Use simple, evocative names for your variables and functions so that anyone can quickly grasp what each one does and spot mistakes.

  • Utilize the built-in solidity function called require to ensure that a particular condition is satisfied before the contract can continue executing. It's a valuable tool for debugging because it halts contract execution when the need is unmet, enabling programmers to locate the problem quickly.

  • The Truffle Debugger is a powerful tool that you can use to debug contracts during the testing stage. It allows developers to review the code, inspect variable values, and revert to previous states.

The Truffle Debugger

  • The Remix IDE is a popular online code editor for Solidity. It contains an integrated debugging function that enables programmers to browse the code and check the values of variables.

Remix IDE

Errors Categories

Syntax, runtime, and logic errors are the most frequent problems engineers face while writing or running code for Solidity contracts.

Syntax Error

A syntax error in a smart contract is a mistake in the code that prevents the computer from understanding it. Simple errors like omitting a semicolon or misusing a term can constitute a syntax fault.

Logical Error

A logical error in a smart contract refers to a mistake in the code that doesn't prevent it from being executed but causes it to produce unexpected or incorrect results.

For instance, a contract transfers money to the incorrect address when sending money from one account to another.

An audit of a smart contract can find logical problems since, sometimes, from the developer's perspective, everything is going according to plan. Even though there might not be a bug in the code, an auditor can still execute a smart contract to look for security vulnerabilities, examine the business logic, and find loopholes.

Runtime Error

Any error during the execution of a contract is called a runtime error. This may occur if a contract fails to handle unexpected inputs or conditions correctly or attempts to carry out an operation prohibited by the underlying blockchain.

For instance, a contract that tries to transfer more money than is allowed in an account would result in a runtime error.

Runtime problems are more challenging to diagnose than syntax faults since they are not known before being deployed on a blockchain and can only occur when a smart contract's state changes.

Common Runtime Errors

Let's look at the most common runtime errors when developing smart contracts for the Ethereum network.

Stack Overflow

In Solidity, a stack can only hold 1024 frames, meaning a function can only call itself 1024 times before a stack overflow happens. If there is an attempt to execute a function recursively and there is no condition to stop it, stack overflow will occur.

pragma solidity ^0.8.0;

contract Overflow {
  function count(uint256 num) public returns (uint256) {
    return count(num + 1);

Overflow o = new Overflow();
o.count(1); // This will cause a Stack Overflow error as the function keeps calling itself infinitely.

Stack Overflow Error in Solidity

Stack Underflow

When there is an attempt to pop a nonexistent variable in assembly language, a stack underflow happens.

Solidity doesn't have a stack-based execution model like some other programming languages, such as C, so it's impossible to cause a Stack Underflow error in Solidity the same way it is in those languages.

However, Solidity does have some exceptions that can be thrown if a contract runs out of gas, which can be thought of as a similar concept to Stack Underflow. Here's an example of Solidity code that can potentially cause an Out of Gas error:

pragma solidity ^0.8.0;

contract Underflow {
  function loop(uint256 num) public returns (uint256) {
    for (uint256 i = 0; i < num; i--) {
      // Do some operation
    return num;

Underflow u = new Underflow();
u.loop(1); // This code may run out of gas as the for loop condition will always be true and the loop will continue indefinitely, potentially causing an Out of Gas error.

Stack Underflow Error in Solidity

Execution Reverted

When a contract stops the execution of a transaction that deviates from its business logic, revert errors happen. Contracts usually include checks for various required criteria. The contract deems a transaction invalid and halts execution if it doesn't meet all requirements.

It's vital to remember that a transaction will only be reverted if it was attempted to be completed but could not be executed based on the smart contract's logic; in this case, the EVM will return an error, and the transaction will be reverted.

pragma solidity ^0.8.0;

contract Revert {
  function transfer(address payable recipient, uint256 amount) public {
    require(amount > 0, "Amount must be greater than zero");

Revert r = new Revert();
r.transfer(address(0), 0); // This code will cause an Execution Reverted error as the `require` statement will fail since the amount is zero, causing the function to revert its execution.


Out-of-gas error occurs when you don't provide enough gas to execute a transaction or gas is insufficient to complete a transaction.

pragma solidity ^0.8.0;

contract OutOfGas {
    function consumeGas() public {
        while (true) {
            // Do some computation that consumes gas

OutOfGas o = new OutOfGas();
o.consumeGas(); // This code may run out of gas as the while loop runs indefinitely, consuming all available gas.

Out-of-Gas error in solidity

Invalid Opcode

The Invalid opcode errors occur when EVM encounters an incompatibility with a contract. For instance, when the contract was compiled with an unsupported compiler.

JUMP Errors

The invalid jump happens when you try to call a function that doesn't exist, such as when you call a function of one contract through another contract that doesn't exist. A similar issue can happen when you use assembly language and point to false memory.

pragma solidity ^0.8.0;

contract JumpError {
  function jump() public returns (uint256) {
    uint256 x = 1;
    if (x == 1) {
      return 1;
    } else {
      return 2;
    return 3; // This code is unreachable and can cause a "JUMP" error.

JumpError j = new JumpError();
j.jump(); // This code may cause a "JUMP" error as the final return statement is unreachable.

JUMP Errors in Solidity

Debugging Tools

This previous section taught us about common errors in building and deploying smart contracts. Now, we will check out the tools for debugging smart contracts.

Hardhat & Truffle

Hardhat is an open-source development environment for Ethereum. It includes tools for developing, testing, and deploying smart contracts. Hardhat also has a built-in debugger allowing developers to review the code and inspect variable values.

Truffle is a popular development framework for Ethereum. It includes a suite of tools for developing, testing, and deploying smart contracts. Truffle also consists of the Truffle Debugger, a powerful tool for debugging contracts during the testing stage.




Remix is a popular online code editor for Solidity. It has a built-in debugging feature lets developers scan the code and inspect variable values.

Remix IDE


Etherscan is a blockchain explorer for Ethereum. It allows developers to inspect and debug contracts deployed on the Ethereum blockchain.


The stage of development and the project's particular requirements will determine the best tool to use for debugging contracts.

Remix and EtherScan are better suited for the deployment stage, while Truffle and Hardhat are better suited for testing. Truffle and Hardhat offer more sophisticated debugging tools, such as stepping code and returning to earlier states. Remix and Etherscan, on the other hand, provide additional visibility and transparency into the deployed contract.

Testing various tools to determine which best suits the project's demands is crucial.


Debugging smart contracts is a critical stage in creating decentralized apps for the blockchain. Web3 developers can ensure that their contracts operate as intended by following the advice and using the resources described in this guide.

As technology and best practices advance, it's critical to keep learning and experimenting with new tools and strategies for debugging contracts.

D_D Newsletter CTA


I'd love to connect with you on Twitter | LinkedIn | GitHub | Portfolio

See you in my next blog article. Take care!!!