> ## Documentation Index
> Fetch the complete documentation index at: https://sidiorresearchlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Transactions

> Learn how to troubleshoot common problems with transactions on HyperPaxeer

## Common Issues

This guide helps you diagnose and fix common transaction problems on HyperPaxeer.

## Transaction Stuck in Mempool

### Symptoms

* Transaction shows as "pending" for extended period
* Transaction doesn't get mined
* No confirmation after several minutes

### Cause

The max fee per gas is too low compared to the current base fee.

### Solution

> [tab] Increase Fee (Replace)
>
> Send a new transaction with the same nonce but higher fee:
>
> ```javascript theme={null}
> import { ethers } from 'ethers';
>
> async function replaceTransaction(originalTx, newMaxFee) {
>   const signer = await provider.getSigner();
>
>   // Get the nonce from the stuck transaction
>   const nonce = await originalTx.nonce;
>
>   // Send new transaction with same nonce, higher fee
>   const newTx = await signer.sendTransaction({
>     ...originalTx,
>     nonce: nonce,
>     maxFeePerGas: newMaxFee, // Higher than before
>     maxPriorityFeePerGas: ethers.parseUnits('2', 'gwei'), // Higher priority
>   });
>
>   console.log('Replacement tx:', newTx.hash);
>   return await newTx.wait();
> }
> ```

> [tab] Cancel Transaction
>
> Send a 0 value transaction to yourself with same nonce:
>
> ```javascript theme={null}
> async function cancelTransaction(stuckTxNonce) {
>   const signer = await provider.getSigner();
>   const address = await signer.getAddress();
>
>   // Get current fee data
>   const feeData = await provider.getFeeData();
>
>   // Send 0 value to yourself with higher fee
>   const cancelTx = await signer.sendTransaction({
>     to: address,
>     value: 0,
>     nonce: stuckTxNonce,
>     maxFeePerGas: feeData.maxFeePerGas * 2n, // Much higher
>     maxPriorityFeePerGas: feeData.maxPriorityFeePerGas * 2n,
>     gasLimit: 21000,
>   });
>
>   console.log('Cancel tx:', cancelTx.hash);
>   return await cancelTx.wait();
> }
> ```

> [!WARNING]
>
> When replacing or canceling a transaction, you must use the **same nonce** as the original transaction. The replacement must also have a **higher gas price** (typically 10%+ more).

***

## Out of Gas Error

### Symptoms

* Transaction reverts with "out of gas" error
* Transaction receipt shows `status: 0`

### Cause

The gas limit was set too low for the transaction's execution.

### Solution

**1. Re-estimate Gas**

```javascript theme={null}
const gasEstimate = await provider.estimateGas(tx);
console.log('Required gas:', gasEstimate.toString());
```

**2. Add Sufficient Buffer**

```javascript theme={null}
const gasLimit = gasEstimate * 150n / 100n; // 50% buffer
```

**3. Check for Contract Issues**

If gas estimates are extremely high:

* Contract may have infinite loops
* Contract may be poorly optimized
* Transaction may be calling expensive operations

***

## Insufficient Funds

### Symptoms

* Error: "insufficient funds for gas \* price + value"
* Transaction rejected before sending

### Cause

Account doesn't have enough HPX to cover: (gasLimit × maxFeePerGas) + value

### Solution

```javascript theme={null}
async function checkSufficientBalance(tx) {
  const signer = await provider.getSigner();
  const address = await signer.getAddress();
  
  // Get current balance
  const balance = await provider.getBalance(address);
  
  // Calculate required balance
  const gasEstimate = await provider.estimateGas(tx);
  const feeData = await provider.getFeeData();
  const maxCost = gasEstimate * feeData.maxFeePerGas;
  const totalRequired = maxCost + (tx.value || 0n);
  
  console.log('Current balance:', ethers.formatEther(balance), 'HPX');
  console.log('Required balance:', ethers.formatEther(totalRequired), 'HPX');
  
  if (balance < totalRequired) {
    throw new Error(`Insufficient funds. Need ${ethers.formatEther(totalRequired - balance)} more HPX`);
  }
  
  return true;
}

// Usage
await checkSufficientBalance(tx);
```

***

## Transaction Reverted

### Symptoms

* Transaction mined but `status: 0` (failed)
* Receipt shows gas used but state didn't change

### Cause

Contract execution failed due to:

* Failed `require()` or `assert()` statement
* Out of gas during execution
* External call failure
* Invalid operation

### Debugging Steps

**1. Check Transaction Receipt**

```javascript theme={null}
const receipt = await provider.getTransactionReceipt(txHash);

if (receipt.status === 0) {
  console.log('Transaction failed!');
  console.log('Gas used:', receipt.gasUsed.toString());
  console.log('Block:', receipt.blockNumber);
}
```

**2. Simulate Transaction**

Use `eth_call` to simulate before sending:

```javascript theme={null}
try {
  const result = await provider.call(tx);
  console.log('Simulation successful:', result);
} catch (error) {
  console.error('Simulation failed:', error.message);
  // Don't send the transaction
}
```

**3. Check Logs and Events**

```javascript theme={null}
const receipt = await provider.getTransactionReceipt(txHash);

receipt.logs.forEach(log => {
  console.log('Event emitted:', log);
});
```

**4. Use Block Explorer**

View detailed error messages on PaxScan:

```
https://paxscan.io/tx/0x...
```

***

## Nonce Issues

### Nonce Too Low

**Error:** "nonce too low"

**Cause:** Transaction uses a nonce that's already been used.

**Solution:**

```javascript theme={null}
// Get the correct nonce
const nonce = await provider.getTransactionCount(address, 'pending');
```

### Nonce Too High

**Error:** "nonce too high"

**Cause:** Transaction uses a nonce higher than expected (gap in nonces).

**Solution:**

```javascript theme={null}
// Always use the next available nonce
const nonce = await provider.getTransactionCount(address, 'latest');
```

### Nonce Management for Multiple Transactions

```javascript theme={null}
async function sendMultipleTransactions(transactions) {
  const signer = await provider.getSigner();
  let nonce = await provider.getTransactionCount(
    await signer.getAddress(),
    'pending'
  );

  const txPromises = transactions.map(async (tx, index) => {
    const txResponse = await signer.sendTransaction({
      ...tx,
      nonce: nonce + index,
    });
    return txResponse.wait();
  });

  return await Promise.all(txPromises);
}
```

***

## Gas Price Too Low

### Symptoms

* Transaction not being picked up
* Sitting in mempool indefinitely

### Solution

Set higher fees:

```javascript theme={null}
const feeData = await provider.getFeeData();

// Set max fee to 2x current
const maxFeePerGas = feeData.maxFeePerGas * 2n;

// Set priority fee for faster inclusion
const maxPriorityFeePerGas = ethers.parseUnits('2', 'gwei');
```

***

## RPC Error: Transaction Underpriced

### Error Message

```
"transaction underpriced"
```

### Cause

Priority fee is too low for current network conditions.

### Solution

```javascript theme={null}
// Get recommended priority fee
const recommendedPriority = await provider.send('eth_maxPriorityFeePerGas', []);

// Use at least the recommended amount
const tx = await signer.sendTransaction({
  ...txData,
  maxPriorityFeePerGas: recommendedPriority,
});
```

***

## Transaction Takes Too Long

### Normal Confirmation Times

| Priority | Expected Time | Block Count |
| - | - | - |
| Low (0 gwei) | 10-30 seconds | 5-15 blocks |
| Standard | 4-10 seconds | 2-5 blocks |
| High (2x priority) | 2-4 seconds | 1-2 blocks |

### If Taking Longer

**1. Check Transaction Status**

```javascript theme={null}
const tx = await provider.getTransaction(txHash);

if (!tx) {
  console.log('Not yet mined');
} else if (!tx.blockNumber) {
  console.log('In mempool, waiting for block');
} else {
  console.log('Mined in block:', tx.blockNumber);
}
```

**2. Check Network Status**

Visit the network status page:

```
https://status.paxeer.app
```

**3. Increase Priority Fee**

If stuck, replace with higher priority fee (see above)

***

## Contract Call Failures

### Common Revert Reasons

> [accordion] Insufficient Allowance
>
> **Error:** "ERC20: transfer amount exceeds allowance"
>
> **Solution:**
>
> ```javascript theme={null}
> // Approve token spending first
> const token = new ethers.Contract(tokenAddress, ERC20_ABI, signer);
> const approveTx = await token.approve(spenderAddress, amount);
> await approveTx.wait();
>
> // Then perform the transfer
> const transferTx = await token.transfer(toAddress, amount);
> ```

> [accordion] Insufficient Balance
>
> **Error:** "ERC20: transfer amount exceeds balance"
>
> **Solution:**
>
> ```javascript theme={null}
> // Check balance first
> const balance = await token.balanceOf(address);
> if (balance < amount) {
>   throw new Error('Insufficient token balance');
> }
> ```

> [accordion] Invalid Parameters
>
> **Error:** Various errors about invalid inputs
>
> **Solution:**
>
> * Validate all inputs before sending
> * Check address formats (valid checksummed addresses)
> * Ensure amounts are in correct units (wei vs ether)
> * Verify array lengths and types

## Debugging Tools

### Using Tenderly

Simulate and debug transactions:

```javascript theme={null}
// Use Tenderly's simulation API
const simulation = await fetch('https://api.tenderly.co/api/v1/account/me/project/my-project/simulate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': 'YOUR_KEY',
  },
  body: JSON.stringify({
    network_id: '125',
    from: fromAddress,
    to: toAddress,
    input: data,
    value: value.toString(),
  }),
});

const result = await simulation.json();
console.log('Simulation result:', result);
```

### Using PaxScan

Check transaction details and error messages:

1. Go to [https://paxscan.io](https://paxscan.io)
2. Search for your transaction hash
3. View execution trace and error messages
4. Check event logs for clues

## Prevention Checklist

Before sending transactions:

* [ ] Estimate gas with `eth_estimateGas`
* [ ] Add 10-20% buffer to gas estimate
* [ ] Check current base fee is reasonable
* [ ] Set appropriate priority fee
* [ ] Verify account has sufficient balance
* [ ] Simulate transaction with `eth_call` first
* [ ] Validate all input parameters
* [ ] Handle errors gracefully in code

## Getting Help

> [card] [Discord Community](https://discord.gg/paxeer)
>
> Ask questions and get help

> [card] [GitHub Issues](https://github.com/paxeer/issues)
>
> Report bugs and issues

> [card] [Block Explorer](https://paxscan.io)
>
> Investigate transactions

> [card] [Status Page](https://status.paxeer.app)
>
> Check network status

## Next Steps

> [card] [Transaction Fees](https://sidiorresearchlabs.mintlify.site/app-developers/guides/transactions/fees.md)
>
> Understand fee structure

> [card] [Gas Parameters](https://sidiorresearchlabs.mintlify.site/app-developers/guides/transactions/parameters.md)
>
> Set optimal parameters

> [card] [Examples](https://sidiorresearchlabs.mintlify.site/examples.md)
>
> View working examples


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.