Debugging Move

Move was designed to be simple and safe, but like with all programming languages, bugs can still occur. This guide will help you debug your Move code and figure out what went wrong.

Please feel free to contribute with additional tooling and information that can help others in the community.

Debugging with the Aptos CLI

Simulation on transaction submission

You can use the Aptos CLI to simulate entry functions prior to executing them.

Normally, a transaction will fail in simulation if it won’t work on-chain. For example:

aptos move run --function-id 0x1::aptos_account::transfer --args address:0x1 u64:1000000000000000000
{
  "Error": "Simulation failed with status: Move abort in 0x1::coin: EINSUFFICIENT_BALANCE(0x10006): Not enough coins to complete transaction"
}

The same applies to Move scripts as well. For example:

 aptos move run-script --script-path <script_path> ...

Local Simulation

Additionally, for some situations, local simulation, may give additional information and print out any debug statements you have in your code.

aptos move run --function-id 0x1::aptos_account::transferred --args address:0x1 u64:1000000000000000000 --local

Simulating transaction locally...
{
  "Result": {
    "transaction_hash": "0x4115316915d409ba4106632c82d4b09220035ffdbd0b86bbe29a586d03d06318",
    "gas_used": 3,
    "gas_unit_price": 100,
    "sender": "78077fe8db589e1a3407170cf8af3bd60a8c95737918c15dd6f49dcbecc7900a",
    "success": false,
    "version": 56634003,
    "vm_status": "status FUNCTION_RESOLUTION_FAILURE of type Verification with message Function 0x1::aptos_account::transferred does not exist"
  }
}

Gas Profiling and Tracing

Adding the gas profile will additionally add the ability to trace how much gas is used in computation:

aptos move run --function-id 0x1::aptos_account::transferred --args address:0x1 u64:1000000000000000000 --profile-gas

Simulating transaction locally using the gas profiler...
Gas report saved to gas-profiling/txn-a90ca655-0x1-aptos_account-transferred.
{
  "Result": {
    "transaction_hash": "0xa90ca6550dcdd7f514f4cdcdee7dc1fbee17082fcf68f3db3e5755a93b89bcfc",
    "gas_used": 3,
    "gas_unit_price": 100,
    "sender": "78077fe8db589e1a3407170cf8af3bd60a8c95737918c15dd6f49dcbecc7900a",
    "success": false,
    "version": 56651618,
    "vm_status": "status FUNCTION_RESOLUTION_FAILURE of type Verification with message Function 0x1::aptos_account::transferred does not exist"
  }
}

And this will generate a gas report viewable in HTML format:

open  gas-profiling/txn-a90ca655-0x1-aptos_account-transferred/index.html

Evaluating performance

aptos move run --function-id 0x1::aptos_account::transfer --args address:0x1 u64:1 --benchmark

Benchmarking transaction locally...
Running time (cold code cache): 22.144458ms
Running time (warm code cache): 669.5µs
{
  "Result": {
    "transaction_hash": "0x7cdf37ff4d798b3ac3f1e860a40428853e381598a511b9291f2a49e5ff6262a0",
    "gas_used": 11,
    "gas_unit_price": 100,
    "sender": "78077fe8db589e1a3407170cf8af3bd60a8c95737918c15dd6f49dcbecc7900a",
    "success": true,
    "version": 56679764,
    "vm_status": "status EXECUTED of type Execution"
  }
}