Debugging failed transactions

Learn how to debug failed Stellar Soroban transactions using Erst’s comprehensive debugging tools

Erst is designed to solve the “black box” debugging experience on Soroban by helping you understand why a transaction failed. This guide walks you through the complete debugging workflow.

Quick start

Debug a failed transaction from any Stellar network:

erst debug <transaction-hash> --network testnet

By default, Erst fetches transaction data from mainnet. Use --network to specify testnet or other networks.

Understanding transaction failures

When a Soroban transaction fails on mainnet, you typically receive a generic XDR error code. Erst bridges the gap between this opaque network error and your source code by:

1. Fetching transaction data
2. Erst uses the Stellar RPC to retrieve:
4. Local simulation
5. The transaction is re-executed locally using the erst-sim Rust binary that integrates with soroban-env-host.
6. Trace decoding
7. Execution steps and failures are mapped back to readable instructions and source code lines (when debug symbols are available).

Interactive trace viewer

Launch an interactive terminal UI to explore transaction execution traces:

erst debug <transaction-hash> --interactive
# or short form
erst debug <transaction-hash> -i

Key features

Search functionality

• Press / to search through traces
• Search across contract IDs, functions, errors, and events
• Case-insensitive by default
• Highlights all matches in yellow
• Current match highlighted in green
• Shows “Match X of Y” status
• Jump between matches with n (next) and N (previous)

Tree navigation

• Expand/collapse nodes with Enter or Space
• Navigate with arrow keys or vim-style j/k
• Expand all nodes with e
• Collapse all nodes with c
• Jump to start with Home or g
• Jump to end with End or G
• Page up/down with PgUp/PgDn

Visual styling

• Color-coded elements:
  • Contract IDs in cyan
  • Function names in blue
  • Errors in red
  • Search matches in yellow
• Depth indentation for clear hierarchy
• Visual indicators for expanded (v) and collapsed (>) nodes

Keyboard shortcuts

Navigation:
  ↑/k         Move up
  ↓/j         Move down
  PgUp        Scroll up one page
  PgDn        Scroll down one page
  Home/g      Jump to start
  End/G       Jump to end
  Enter/Space Toggle expand/collapse

Search:
  /           Start search
  Enter       Execute search
  n           Next match
  N           Previous match
  ESC         Clear search

Tree:
  e           Expand all nodes
  c           Collapse all nodes

Other:
  ?/h         Show help
  q/Ctrl+C    Quit viewer

Debugging offline

Debug a transaction envelope from stdin without RPC access:

erst debug < tx.xdr

This is useful when:

• Working with pre-downloaded transaction data
• Debugging in air-gapped environments
• Testing with custom transaction envelopes

Common debugging workflows

Search for specific errors

1. Launch interactive viewer
2. erst debug abc123...def --interactive
   

3. Press / to start search
4. Type your search term, such as:
6. Navigate matches
7. Use n and N to jump between all occurrences of your search term.

Trace execution flow

1. Start with collapsed view
2. Press c to collapse all nodes for a high-level overview.
3. Expand interesting branches
4. Navigate to a node and press Enter to see its children.
5. Follow the call chain
6. Expand nodes progressively to understand the execution path.

Find contract interactions

1. Search for contract ID
2. Press / and type the first few characters of a contract address:
3. CDLZFC3
   

4. Review all calls
5. Use n to jump through every interaction with that contract.
6. Expand for details
7. Press Enter on matches to see function arguments and results.

Source mapping

To map WASM instruction failures to Rust source code lines, you need to compile your contracts with debug symbols enabled.

When debug symbols are available, Erst can:

• Show which Rust source line caused a failure
• Generate GitHub links to source code locations
• Provide more context about execution state

See the Source Mapping feature for setup instructions.

Error suggestions

Erst includes a heuristic-based engine that suggests potential fixes for common Soroban errors:

erst debug abc123...def

If a known error pattern is detected, you’ll see suggestions like:

[ERROR] InsufficientBalance

💡 Suggestions:
  • Check that the source account has sufficient funds
  • Verify the token contract has approved the transfer
  • Ensure the amount doesn't exceed the available balance

Performance considerations

Caching

Erst automatically caches transaction data to improve performance:

# Check cache status
erst cache status

# Clean old entries
erst cache clean

Cached data enables:

• Faster repeated debugging of the same transaction
• Offline analysis after initial fetch
• Reduced load on RPC endpoints

Network timeout

For slow or unreliable networks, increase the timeout:

export ERST_RPC_TIMEOUT=60
erst debug <transaction-hash>

Troubleshooting

Transaction not found

Error: transaction not found on network

Solutions:

• Verify the transaction hash is correct
• Check you’re using the right network (--network testnet)
• Ensure the transaction exists on the specified network
• Try a different RPC endpoint if available

XDR decode error

Error: failed to decode XDR

Solutions:

• Check that the XDR format is correct
• Verify you’re not mixing testnet and mainnet data
• Ensure the XDR isn’t truncated or corrupted

Empty trace output

No trace data available

Solutions:

• Transaction may have failed before execution started
• Check that diagnostic events are enabled on your RPC
• Try debugging with --verbose for more details

Next steps

Using flamegraphs

Profile CPU and memory usage during contract execution

Working with sessions

Save and resume debugging sessions

Local WASM replay

Test contracts locally without network access

Cache management

Optimize cache usage for faster debugging