Skip to main content
The debug command is the primary entry point for debugging Soroban transactions. It fetches transaction data from the network, simulates execution locally, and provides detailed error traces.

​
Usage

erst debug <transaction-hash> [flags]

​
Description

The debug command helps you understand why a Soroban transaction failed by:
  • Fetching the transaction envelope and ledger state from the network
  • Simulating execution locally with detailed instrumentation
  • Decoding errors and mapping them to readable instructions
  • Tracking token flows and contract events
  • Generating execution traces for further analysis

​
Examples

erst debug abc123...def

​
Flags

​
Network configuration

​
--network
string
default:"mainnet"
Stellar network to use: testnet, mainnet, or futurenet
​
--rpc-url
string
Custom Soroban RPC URL (overrides default for network)
​
--rpc-token
string
RPC authentication token (can also use ERST_RPC_TOKEN env var)

​
Local testing

​
--wasm
string
Path to local WASM file for testing without deploying
​
--optimize
boolean
default:"false"
Run dead-code elimination on local WASM before simulation
​
--args
string[]
Mock arguments to pass to the local WASM execution

​
Output options

​
--verbose
boolean
default:"false"
Print detailed simulation output and diagnostic informationAlias: -v
​
--interactive
boolean
default:"false"
Launch interactive trace viewer after debuggingAlias: -i
​
--theme
string
Color theme for output: default, deuteranopia, protanopia, tritanopia, or high-contrast

​
Advanced options

​
--protocol-version
uint32
Override protocol version for simulation (20, 21, 22, etc.)
​
--sim-path
string
Path to erst-sim binary (overrides auto-discovery)

​
Interactive mode

When using --interactive, the debug command launches a terminal UI with:
  • Search: Press / to search through traces
  • Navigation: Use arrow keys to expand/collapse nodes
  • Help: Press ? or h to see all keyboard shortcuts
  • Syntax highlighting: Color-coded contract IDs, functions, and errors
  • Match counter: See “Match 2 of 5” while searching

​
Performance profiling

When using --profile, generates an interactive flamegraph visualizing CPU and memory consumption: 
# Generate interactive HTML flamegraph
erst debug --profile abc123...def

# Generate raw SVG
erst debug --profile --profile-format svg abc123...def
The flamegraph includes:
  • Hover tooltips with frame details
  • Click-to-zoom for specific call stacks
  • Search/highlight to find frames by name
  • Dark mode support
  • trace - Navigate execution traces interactively
  • compare - Compare local vs on-chain execution
  • profile - Export trace as pprof profile for gas analysis
  • session - Save debugging session for later