# DeFi Transaction Failure Playbook

A comprehensive guide to diagnosing and fixing common DeFi transaction failures.

## 1. Insufficient Token Balance

**Symptoms:** `ERC20: transfer amount exceeds balance`, `ERC20InsufficientBalance`

**Root Cause:** Your wallet doesn't have enough of the token you're trying to transfer or swap.

**Fix Steps:**
1. Check your wallet balance for the exact token.
2. Account for gas fees — keep enough native token (ETH/MATIC/BNB) for gas.
3. If swapping, the router needs the full input amount in your wallet.
4. Acquire more tokens via a bridge, CEX withdrawal, or another swap.

---

## 2. Token Allowance / Approval Missing

**Symptoms:** `ERC20: insufficient allowance`, `ERC20InsufficientAllowance`

**Root Cause:** You haven't approved the DeFi contract to spend your tokens, or the approved amount is too low.

**Fix Steps:**
1. Send an `approve(spender, amount)` transaction to the token contract.
2. In wallet UIs (MetaMask, Rabby): the dApp typically prompts you to approve.
3. Set the amount to at least the swap/deposit amount, or use unlimited approval.
4. Wait for the approval tx to confirm, then retry.

---

## 3. Slippage Exceeded

**Symptoms:** `UniswapV2: INSUFFICIENT_OUTPUT_AMOUNT`, `Too little received`, `SLIPPAGE`

**Root Cause:** The price moved between submission and execution. The actual output was less than your minimum acceptable amount.

**Fix Steps:**
1. Increase slippage tolerance: 0.5% → 1-3% for stable pairs, 5-12% for volatile tokens.
2. For fee-on-transfer tokens, set slippage ≥ the transfer tax (often 10-15%).
3. Use a DEX aggregator (1inch, Paraswap, CowSwap) for better routes.
4. During high volatility, wait for the market to stabilize.
5. ⚠ Higher slippage = more exposure to MEV sandwich attacks.

---

## 4. Swap Deadline Expired

**Symptoms:** `UniswapV2: EXPIRED`, `Transaction too old`, Deadline passed

**Root Cause:** The transaction wasn't mined before the deadline timestamp.

**Fix Steps:**
1. Simply retry — a fresh deadline is set automatically.
2. Increase the deadline setting if available (e.g., 20-30 minutes).
3. Use a higher gas price during network congestion to get mined faster.

---

## 5. Out of Gas

**Symptoms:** Transaction status "failed", gas used ≈ gas limit (>95%)

**Root Cause:** The smart contract execution consumed more gas than the limit you set.

**Fix Steps:**
1. Increase gas limit by 30-50% (do NOT increase gas price — that's different).
2. Complex DeFi operations (multi-hop swaps, flash loans) need more gas.
3. Simulate the tx first with Tenderly or a local fork.
4. If it always runs out of gas, the contract may have a bug or infinite loop.

---

## 6. Insufficient Liquidity

**Symptoms:** `UniswapV2: INSUFFICIENT_LIQUIDITY`, swap reverts on large amounts

**Root Cause:** The liquidity pool doesn't have enough tokens to fill your order.

**Fix Steps:**
1. Reduce the swap amount.
2. Use a DEX aggregator to split across multiple pools.
3. Try a different DEX or trading pair.
4. For large orders, use limit orders or OTC platforms.

---

## 7. Access Denied / Not Authorized

**Symptoms:** `Ownable: caller is not the owner`, `AccessControl: missing role`

**Root Cause:** The function requires admin/owner privileges that your wallet doesn't have.

**Fix Steps:**
1. Verify you're using the correct wallet.
2. Check the contract — the function may be admin-only.
3. If you need access, contact the governance or multisig holders.

---

## 8. Contract Paused

**Symptoms:** `Pausable: paused`, `Contract is paused`

**Root Cause:** The contract admin has paused operations (maintenance, security incident).

**Fix Steps:**
1. Check the project's official channels for announcements.
2. Wait for the contract to be unpaused.
3. Do NOT interact with unofficial "rescue" contracts.

---

## 9. Arithmetic Overflow / Underflow

**Symptoms:** `Panic(0x11)`, `ds-math-sub-underflow`, `SafeMath: subtraction overflow`

**Root Cause:** A math operation exceeded the valid range (usually a contract bug).

**Fix Steps:**
1. This is typically a contract bug — report it with the tx hash.
2. Do NOT retry with the same parameters.
3. Check if a newer version of the contract has been deployed.

---

## 10. Nonce Issues

**Symptoms:** `nonce too low`, `nonce too high`, `replacement transaction underpriced`

**Root Cause:** Your wallet's transaction counter is out of sync, often due to pending or stuck transactions.

**Fix Steps:**
1. MetaMask: Settings → Advanced → Clear Activity Tab Data.
2. If you have stuck pending transactions, speed them up or cancel them.
3. For manual nonce management, query the latest nonce from the chain.

---

## 11. Blacklisted Address

**Symptoms:** `Blacklisted`, token transfer reverts with no clear reason for USDT/USDC

**Root Cause:** Your address has been blacklisted by the token issuer (Circle, Tether).

**Fix Steps:**
1. Check if the token has a blacklist by reading the contract.
2. Contact the token issuer if you believe it's an error.
3. Use a different address if possible.

---

## 12. Reentrancy Guard

**Symptoms:** `ReentrancyGuard: reentrant call`

**Root Cause:** The contract detected a re-entrant call pattern and blocked it for security.

**Fix Steps:**
1. Do NOT attempt to bypass this — it's a security protection.
2. Simplify your transaction (avoid calling contracts that call back into the original).
3. If developing, restructure your code to avoid reentrancy patterns.
