Debug a Contract

You can use Solidity console logs to debug contracts that are running on the simulated Hardhat local node.

To debug a contract, deploy it to the built-in Hardhat Local Node environment, and make all logging changes only in a local debugging branch or temporary working copy.

The built-in local environment is named hardhatnode and uses http://127.0.0.1:8545 with chain ID 31337. It is not a saved Oracle Blockchain Platform or other EVM environment. When you select it to deploy or run a contract and no local node is listening, Blockchain App Builder for Besu starts a Hardhat node for the selected project and opens the Hardhat local node terminal.

1. At the top of the Solidity file that contains the code path that you want to inspect, add the Hardhat console import.

   import "hardhat/console.sol";

2. Add a temporary log in the function or internal helper to investigate.

   console.log("value", value);

   The following code shows common log examples.

   console.log("entered transfer");
   console.log("caller", msg.sender);
   console.log("amount", amount);
   console.log("is allowed", isAllowed);

   Use the value type that matches the variable that you are inspecting. These examples cover strings, addresses, integer values, and Boolean values. Keep log statements narrow and temporary; do not log private keys, authentication tokens, or other credentials.
3. In the Deploy / Execute form, select Clean if you need to discard old artifacts, and then select Compile.
4. Select Hardhat Local Node as the environment.
5. Deploy the local contract instance, or use a local proxy that is already deployed. Satisfy any project-specific deployment prerequisites, such as governance contracts, in the local network.
6. Open the Execute pane, select the local token or account proxy, enter the function parameters, and then select Query or Invoke.

   Query completes a local call and Invoke sends a local transaction. Either can reach a logged code path, but only an invocation changes the simulated chain state.

7. Open the Hardhat Local Node terminal in Visual Studio Code and inspect the emitted log lines.
8. Remove the hardhat/console.sol import statement and every temporary console.log statement.
9. Clean and compile again before committing code or using an Oracle Blockchain Platform Besu, other EVM, or production environment.

Do not attempt to use the Hardhat-only instrumentation for Oracle Blockchain Platform or other EVM environments. Instead, use ordinary application events, off-chain transaction tracing, or environment-approved observability. Console logging is not a replacement for production diagnostics.

Troubleshooting the Debugging Process

Condition	Resolution
hardhat/console.sol cannot be found	Run Install Dependencies in the selected project, and then compile again. The import is provided by the project’s Hardhat dependency.
The local node does not start	Confirm that the selected project contains hardhat.config.ts or hardhat.config.js, verify Node.js and npm are available to Visual Studio Code, and check the Hardhat Local Node terminal for startup errors.
No logs are displayed	Confirm that Hardhat Local Node is the selected environment, that the invoked code path reaches the log statement, and that you are viewing the Hardhat Local Node terminal rather than an Oracle Blockchain Platform or project terminal.
The application is using old code	Select Clean, then Compile, before deploying or invoking again.
A non-local build or deployment fails after debugging	Remove every hardhat/console.sol import and console.log call, then clean and compile the project again.