Skip to main content
This guide will walk you through debugging your first failed Soroban transaction using Erst.

​
Prerequisites

Before you begin, make sure you have:
  • Erst installed and available in your PATH
  • A transaction hash from a failed Soroban transaction
  • Access to a Stellar RPC endpoint (default: public testnet)
If you don’t have a failed transaction handy, you can use one from testnet for this tutorial.

​
Basic debugging workflow

1

Debug a transaction

The simplest way to debug a transaction is to provide its hash:
erst debug <transaction-hash>
For example, on testnet:
erst debug abc123...def --network testnet
This command will:
  • Fetch the transaction envelope from the Stellar network
  • Retrieve the ledger state at the time of execution
  • Simulate the transaction locally
  • Display detailed error traces and diagnostic events
The --network flag defaults to testnet. Use --network mainnet for mainnet transactions.
2

Explore with interactive mode

For complex transactions, use the interactive trace viewer:
erst debug <transaction-hash> --interactive
Or use the shorthand:
erst debug <transaction-hash> -i
The interactive mode provides:
  • Search functionality - Press / to search through traces
  • Tree navigation - Expand/collapse nodes with arrow keys
  • Syntax highlighting - Color-coded contract IDs, functions, and errors
  • Fast navigation - Jump between search matches with n/N
  • Help overlay - Press ? or h for keyboard shortcuts
3

Analyze the results

Erst displays:
  • Transaction execution trace
  • Contract invocation hierarchy
  • Error messages with context
  • Resource consumption metrics
  • Diagnostic events from the VM
Look for:
  • Red-highlighted errors in the trace
  • Contract IDs where failures occurred
  • Function names in the call stack
  • Error codes and messages

​
Common debugging scenarios

Debug a transaction from testnet or mainnet:
erst debug abc123...def --network testnet
The transaction data is automatically cached for offline analysis.

​
Performance profiling

Generate interactive flamegraphs to visualize where your contract spends time and memory: 
erst debug --profile <transaction-hash>
This creates an interactive HTML file (<tx-hash>.flamegraph.html) with:
  • Hover tooltips showing function details
  • Click-to-zoom for focusing on specific call stacks
  • Search/highlight to find frames by name
  • Dark mode support
erst debug --profile --profile-format html <transaction-hash>
Generates an interactive HTML flamegraph you can open in any browser.

​
Managing sessions

Save debugging sessions to resume work later or share with your team:
1

Debug and save

First, debug a transaction:
erst debug abc123...def --network testnet
2

Save the session

After debugging, save the session:
erst session save
Or with a custom ID:
erst session save --id my-debug-session
3

List sessions

View all saved sessions:
erst session list
This displays session IDs, transaction hashes, timestamps, and status.
4

Resume a session

Resume debugging from where you left off:
erst session resume <session-id>

​
Cache management

Erst caches transaction data to improve performance and enable offline analysis. 
erst cache status
Cache location: ~/.erst/cache
The cache uses an LRU (Least Recently Used) strategy to manage disk space automatically.

​
Advanced options

​
Override ledger timestamp

Test how your contract behaves at different points in time: 
erst debug <tx-hash> --timestamp 1672531200
The timestamp is in Unix epoch format.

​
Time window simulation

Run simulations across a time range: 
erst debug <tx-hash> --window 3600
This simulates the transaction across a 3600-second (1 hour) window.

​
Getting help

erst --help
The erst doctor command diagnoses common configuration issues and provides recommendations.

​
Example workflow

Here’s a complete workflow for debugging a failed transaction: 
# 1. Debug the transaction interactively
erst debug abc123...def --network testnet --interactive

# 2. Generate a performance profile
erst debug abc123...def --profile

# 3. Save the session for later
erst session save --id failed-token-transfer

# 4. Check cache status
erst cache status

# 5. Resume the session later
erst session resume failed-token-transfer

​
Troubleshooting

​
Transaction not found

If Erst can’t find your transaction:
  1. Verify the transaction hash is correct
  2. Check you’re using the right network (--network testnet or --network mainnet)
  3. Ensure the RPC endpoint is accessible
  4. Try a custom RPC with --rpc <url>

​
Simulation errors

If simulation fails:
  1. Run diagnostics: erst doctor
  2. Check Rust simulator is built: cd simulator && cargo build --release
  3. Clear cache and retry: erst cache clear --force
  4. Enable verbose output: erst debug <tx-hash> --verbose

​
Network timeouts

If you experience network timeouts:
  1. Use a faster RPC endpoint with --rpc
  2. Check your internet connection
  3. Try again later (RPC may be temporarily unavailable)
If you’re debugging mainnet transactions with sensitive data, be aware that Erst caches transaction data locally.

​
Next steps

Now that you’ve debugged your first transaction, explore:

Interactive trace viewer

Learn advanced trace navigation techniques

Performance profiling

Optimize contract performance with flamegraphs

Session management

Advanced session workflows and team collaboration

Contributing

Help improve Erst on GitHub