Debugging Failed Transactions

Learn how to debug reverted transactions using trace analysis tools. This guide covers common failure patterns and their fixes based on real production cases.

Prerequisites

Before you begin, you need:

The transaction hash of the failed transaction
Access to a trace analysis tool

Blocksec Explorer

View detailed call traces and analyze transactions

Tenderly Debugger

Simulate and debug transactions step-by-step

Core Debugging Workflow

Follow these steps to diagnose most transaction failures.

Find the Revert Location

Open the transaction in Blocksec or Tenderly and identify:

The top-level revert reason (if available)
The first revert in the call tree (this is often the actual root cause)
The contract or call before the revert (this is the failing action)

Trace tools sometimes show multiple errors. When the UI summary conflicts with the raw trace, trust the raw trace.

Classify the Failure

Most reverts fall into these categories:

Category	Common Indicators
Out of gas	Trace ends abruptly, OOG error
Insufficient allowance	`transfer amount exceeds allowance`
Insufficient balance	`insufficient balance`, `transfer amount exceeds balance`
Missing msg.value	`insufficient balance for transfer` on native token
Slippage exceeded	Min output checks fail
Oracle issues	`StalePrice`, bad feed errors
Deadline expired	`EXPIRED`, `Transaction too old`
Token restrictions	Transfer blocked, tax fees, blacklist

Once you identify the category, the fix becomes clear.

Compare Expected vs Actual Inputs

Aggregator and router failures often stem from input mismatches:

gasLimit on-chain vs gasLimit from /quote or /stepTransaction
Approval amount vs actual spend amount
msg.value sent vs msg.value required
minAmountOut vs actual output at execution
Token address or price feed ID errors

Reproduce and Test

Simulate the failed call with identical calldata and state. Then change one variable at a time:

Increase gasLimit
Add or adjust msg.value
Relax slippage parameters

If changing one variable makes the simulation succeed, you have found the root cause.

Common Failure Modes

A) Out of Gas

Symptom

The trace ends abruptly or shows an out-of-gas (OOG) error.

How to Confirm

Check the transaction’s gasLimit
Look for OOG in the revert reason
Re-simulate with a higher gasLimit (use the value from the quote API)

Root Cause

The transaction used a lower gasLimit than the quote recommended. Wallets or relayers sometimes override gas settings.

Fix

Use the exact gasLimit from the quote response
Add a 10–20% safety buffer if your product allows it
Verify that wallets and relayers do not clamp gas values

Example

The API returned sufficient gasLimit, but the on-chain transaction reverted. Re-simulating with the correct gasLimit succeeded.

B) Insufficient Allowance

Symptom

Revert message: transfer amount exceeds allowance

How to Confirm

Find the transferFrom(...) call in the trace
Identify which spender is pulling funds
Check allowance(owner, spender) at the execution block

Root Cause

The user either did not approve, approved the wrong spender, or approved less than the required amount. A previous transaction may have consumed the allowance.

Fix

Prompt an approval for the correct token and spender
Consider infinite approval vs exact approval tradeoffs

Example

Transaction reverted due to insufficient allowance

C) Missing msg.value

Symptom

Errors such as:

insufficient balance for transfer
Native value forwarding fails

How to Confirm

Check the transaction’s msg.value in Tenderly
Find where the router forwards ETH in the trace
Look for balance failures at that point

Root Cause

The route requires native tokens (for fees, bridged gas, or protocol payments), but the transaction sent value=0.

Fix

Include the msg.value returned by the API
Verify that relayers and wallets do not drop the value field

Example

The transaction failed because msg.value was missing despite the API returning a non-zero value.View in Tenderly

D) Stale Oracle Price

Symptom

Revert message: PythErrors.StalePrice()

How to Confirm

Look for getPriceNoOlderThan(..., age=N) reverting in the trace.

Root Cause

The oracle data is too old, or the pool uses an incorrect feed ID that is not being updated.

Fix

Contact LI.FI support to report the issue.

Example

PythErrors.StalePrice() occurred because a pool used an incorrect feed ID.View in Tenderly

E) Insufficient Token Balance

Symptom

Revert message: insufficient balance or transfer amount exceeds balance

How to Confirm

Find the token transfer in the trace
Identify the “from” address
Check balanceOf(from) at execution time

Root Cause

The user’s balance changed between quote and execution. Fee-on-transfer or rebasing tokens can cause unexpected balance changes.

Fix

Re-quote and verify balances immediately before sending
For fee-on-transfer tokens, contact LI.FI support to add the token to the deny list

Example

Transaction reverted due to insufficient balance

F) Slippage Exceeded

Symptom

Revert related to minimum output or slippage checks (exact message varies by DEX).

How to Confirm

Find the swap step and compare:

amountOutMin or minReturnAmount
Actual computed amountOut

If amountOut < minReturnAmount, the transaction reverts.

Root Cause

Price movement, MEV extraction, volatile pools, low liquidity, or stale quotes.

Fix

Increase slippage tolerance (15–25% for volatile or new tokens)
Execute within 60–90 seconds of quoting

Example

G) Token Transfer Restriction

Symptom

The final swap step fails with SafeERC20: low-level call failed.

How to Confirm

In the trace, look for:

A transferFrom call that reverts
A nested external call that fails (often to a tax wallet or fee handler)
The error bubbling up as SafeERC20: low-level call failed

Root Cause

Some tokens have custom transfer logic that fails under certain conditions. For example, tokens with sell taxes may call external contracts that reject ETH or revert unexpectedly.

Fix

Treat the token as incompatible for sell routes
Report to LI.FI support for addition to the token deny list

Use token risk scanners like honeypot.is or GoPlus to check for honeypot flags, sell restrictions, or abnormal taxes.

Example

The router failed to transfer tokens because the token’s tax wallet rejected ETH.View in Blocksec

H) Broken Pool (Math Failure)

Symptom

Revert inside pool math, such as Curve’s get_D failing to converge after 255 iterations.

How to Confirm

The trace shows a revert in pool math functions (get_D, invariant computation) with a raise statement.

Root Cause

The pool is broken, often due to a compromised token causing extreme imbalance or invalid state.

Fix

Contact LI.FI support to blacklist the pool.

Example

A Curve pool’s get_D function failed to converge. The Curve team confirmed the pool was broken.View in Tenderly

I) Reentrancy Lock (UniswapV2 LOCKED)

Symptom

Revert message: UniswapV2: LOCKED

How to Confirm

In the trace:

The Uniswap V2 pair transfers a token
The token’s transfer logic calls back into the same pair
The pair’s reentrancy lock triggers

Root Cause

A token with callback or fee-swap logic re-enters the pair during transfer. This often happens with misconfigured fee-on-transfer tokens.

Fix

Contact LI.FI support to blacklist the pool.

Example

Swaps involving WeightedIndex reverted with UniswapV2: LOCKED. KyberSwap blacklisted the affected pool.View in Tenderly

J) Fee-on-Transfer Token Failure

Symptom

Revert due to insufficient balance mid-route, even though the user had enough tokens initially.

How to Confirm

The trace shows:

An earlier hop receives less tokens than expected
A later hop tries to transfer the originally calculated amount
The balance check fails

Root Cause

Fee-on-transfer (FoT) or deflationary tokens take a fee during transfer. The route assumes exact amounts, but the actual received amount is less than calculated.

Fix

Contact LI.FI support to add the token to the deny list.

Example

fBOMB failed with Max20: insufficient balance because its deflationary mechanism broke the route’s exact calculations.

K) DEX Reentrancy Protection

Symptom

Revert caused by a pool-level reentrancy lock, especially with fee-on-transfer tokens.

How to Confirm

The trace shows a revert at the pool with reentrancy guard behavior, similar to “LOCKED” but protocol-specific.

Root Cause

Newer DEXs add reentrancy protections that conflict with fee-on-transfer or callback tokens.

Fix

Contact LI.FI support to blacklist the pool.

Example

Kodiak v2 pools added reentrancy locks that caused fee-on-transfer tokens to revert.View in Tenderly

L) Expired Deadline

Symptom

Revert messages such as:

Transaction too old
EXPIRED
SwapRouter: EXPIRED

How to Confirm

Find the encoded deadline in the calldata (usually a 32-byte word)
Convert the hex value to Unix time
Compare to the block timestamp when the transaction was mined

If block_timestamp > deadline, the router rejects the transaction.Example calculation:

Deadline: 0x6951e2e0 = 1,766,974,176
Block timestamp: 1,766,975,579
Delta: 1,403 seconds (~23 minutes late)

View VM trace

Root Cause

The transaction was submitted too late due to slow signing, mempool congestion, low gas price, or relayer delays.

Fix

Get a fresh quote and submit immediately
Increase gas price for stuck transactions
Do not reuse old calldata

Late execution often means the market has moved. Even without an explicit deadline revert, stale quotes frequently fail due to slippage. Always re-quote.

Quick Decision Checklist

Follow these steps when debugging a failed transaction:

Find the First Revert

Look at the call tree, not just the UI headline. The first revert is usually the root cause.

Identify the Category

Check	Action
Out of gas?	Compare submitted vs recommended `gasLimit`
Allowance?	Check `allowance(owner, spender)`
Balance?	Check `balanceOf` at execution block
Missing value?	Compare transaction value vs required value
Slippage?	Compare `minOut` vs actual output
Oracle?	Look for stale price or wrong feed ID
Token issue?	Check for transfer reverts or false returns

Simulate the Transaction

Use Tenderly or Blocksec to reproduce the failure with identical parameters.

Test Single Changes

Modify one variable at a time (gas, value, approval, slippage) until the simulation succeeds.

Quick Reference

Failure	Key Indicator	Fix
Out of gas	Trace ends abruptly, OOG error	Use `gasLimit` from quote
Allowance	`transfer amount exceeds allowance`	Approve correct spender
Balance	`insufficient balance`	Re-quote and verify balance
Missing value	Native transfer fails	Include `msg.value` from API
Slippage	Min output check fails	Increase slippage, execute faster
Stale oracle	`StalePrice` errors	Report to LI.FI support
Token restriction	`SafeERC20: low-level call failed`	Report token for deny list
Broken pool	Math convergence fails	Report pool for blacklist
Reentrancy	`LOCKED` errors	Report pool for blacklist
Deadline expired	`EXPIRED`	Re-quote and execute quickly

Error Codes

API error code reference

Common Issues FAQ

Frequently asked troubleshooting questions

Status Tracking

Track transaction status

Slippage & Price Impact

Understand slippage settings

Integration

Troubleshooting

​Prerequisites

Blocksec Explorer

Tenderly Debugger

​Core Debugging Workflow

​Common Failure Modes

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Example

​Symptom

​How to Confirm

​Root Cause

​Fix

​Quick Decision Checklist

​Quick Reference

​Related Resources

Error Codes

Common Issues FAQ

Status Tracking

Slippage & Price Impact

Prerequisites

Core Debugging Workflow

Common Failure Modes

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Example

Symptom

How to Confirm

Root Cause

Fix

Quick Decision Checklist

Quick Reference

Related Resources