Free tools Windows power users keep installed
One-click scans. No signup required.
Use truffle debug to replay a mined transaction and step through its Solidity execution, or add Truffle’s debug() helper to pause a JavaScript test at a contract operation. For a revert that already happened, use the transaction hash with truffle debug; the in-test helper does not currently handle reverted transactions.
What Truffle’s debugger does
truffle debug replays a historical blockchain transaction and maps execution back to Solidity source. It is not a live debugger: the transaction must already exist on the connected chain, and Truffle needs the relevant source code and compiled artifacts to display useful source-level execution. Matching compilation output matters, and the Truffle debugger guide warns that optimized builds may not debug reliably. See Truffle’s debugger guide.
The replay can help investigate successful transactions as well as failed and out-of-gas transactions. You can step through Solidity statements, or switch to individual EVM instructions when the source view does not explain the behavior.
Debug a transaction by hash
- Start or connect to a chain. Use Ganache, Truffle Develop, or another Ethereum client/provider. Truffle Develop starts its own development blockchain; Truffle Console instead connects to an existing client such as Ganache or geth. Both provide an interactive console with Truffle commands and contract abstractions. See Truffle’s console documentation.
- Compile the contracts. Run
truffle compilein the project so the debugger has source maps and artifacts. For a contract deployed elsewhere, the local build may not match the deployed code; when supported source is verified, you can try fetching it as described below. - Get the transaction hash. Copy it from the client or transaction output. With Truffle Develop, start it using
truffle develop --logto expose transaction hashes in its log. - Launch the debugger. In the Truffle project, run
truffle debug <transaction_hash> --network <network_name>. Alternatively, connect directly withtruffle debug <transaction_hash> --url <provider_url>. The command reference also documents startingtruffle debugwithout a hash and loading a transaction after the debugger opens. See the Truffle CLI reference. - Step through execution. Set a breakpoint near the code of interest, then step or inspect state as needed. For a revert, follow execution to the failing operation and inspect the surrounding calls and values; for out-of-gas, locate how far execution proceeds and whether the failure occurs in a loop, call, or other operation.
Debugger keys and what they do
| Key | Action | When to use it |
|---|---|---|
o |
Step over the current source line | Continue without entering a called function. |
i |
Step into the current function call or contract creation | Inspect execution inside a callee or constructor. |
u |
Step out of the current function | Return to the caller’s execution. |
n |
Step to the next logical statement or expression | Advance at source level. |
; |
Step one EVM instruction | Investigate behavior that is unclear at Solidity source level. |
b |
Set a breakpoint by line, file, relative line, or current location | Pause at a specific point rather than stepping from the beginning. |
g / G |
Enable / disable stepping through compiler-generated sources | Useful when generated code obscures the Solidity flow; support is documented for Solidity 0.7.2 and later. |
r |
Reset to the beginning of the transaction | Replay after changing your breakpoint or investigation approach. |
h / q |
Show help / quit | Check available controls or exit the debugger. |
For exact command behavior and version-specific details, consult the debugger guide.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall#1 Best Overall
Debug an operation inside a JavaScript test
When a test operation is not a previously mined transaction you need to replay, Truffle v5.1 and later documents a global debug() helper. Wrap the contract operation and run the test with --debug:
await debug(myContract.myFunction(...))truffle test --debugTruffle pauses at the wrapped operation and opens the debugger, where you can set breakpoints and inspect variables. This approach can also inspect read-only calls. It does not currently handle reverted transactions; for an operation that reverts, use direct transaction debugging where a transaction hash is available. See the debugger guide and the test command reference.
Choose the right diagnostic for the failure
| Problem | Use | What it tells you |
|---|---|---|
| A mined transaction reverted or ran out of gas | truffle debug <hash> |
Historical execution, source-level stepping, and instruction-level inspection. |
| A contract operation in a JavaScript test needs inspection | debug(operation) with truffle test --debug |
Pauses at the operation for breakpoints and variable inspection; reverted operations are not supported by this in-test feature. |
| A transaction or deployment revert needs a mixed-language trace | --stacktrace |
JavaScript-and-Solidity stack trace. The CLI reference says it does not apply to calls or gas estimates. |
| A stack trace needs all contracts compiled with debug settings | --stacktrace-extra |
Combines stack tracing with --compile-all-debug. |
| The failure may be in EVM execution or provider communication | Ganache CLI logging options | --logging.debug=true logs EVM opcodes; --logging.verbose=true logs detailed RPC requests. |
These diagnostics address different layers: a stack trace points to a call path, the transaction debugger replays execution, and Ganache logging exposes opcode or RPC activity. The CLI reference documents the stack-trace flags, while the Ganache CLI documentation describes logging options.
Debug calls to external contracts
If execution enters a contract that is not in your project, try --fetch-external with the network option: truffle debug <transaction_hash> --fetch-external --network <network_name>. Truffle documents fetching verified external source through Etherscan, and later versions also document Sourcify support. Availability depends on source verification and the Truffle version. Outside a Truffle project, the CLI also accepts a provider URL with --url. See the debugger guide and the CLI reference.
Common reasons the debugger view is incomplete
- Missing or mismatched artifacts: compile the project and ensure the source and build correspond to the deployed contract. A debugger can replay chain execution, but accurate source mapping depends on the compilation output.
- Optimized compilation: Truffle’s debugger guide cautions that optimized builds may not debug reliably. If source stepping is confusing, treat the mapping as a limitation rather than proof that the on-chain execution differs from the source.
- Unverified external code: fetching external source relies on verification support and availability; unverified code may not appear as readable Solidity.
- Wrong diagnostic layer: use
--stacktracefor transaction or deployment reverts, not calls or gas estimates; use Ganache opcode or verbose RPC logs when the issue may be below Solidity-source level.
For deployment and testing practices, Truffle’s test reference recommends Ganache or Truffle Develop for normal development and testing, and an official Ethereum client before production deployment: Truffle test and configuration documentation.
Quick Recap
Rank #4
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
