Skip to main content
This guide covers common issues you may encounter when using Gelato’s Paymaster and Bundler infrastructure, along with their solutions.

Common Error Codes

ERC-4337 Error Codes

Common Issues

1. UserOperation Execution Reverted

Symptoms:
  • Error message contains “execution reverted”
  • Transaction fails after submission
Causes:
  • Invalid calldata encoding
  • Target contract reverted
  • Insufficient token balance for the operation
Solutions:

2. Paymaster Validation Failed

Symptoms:
  • Error contains “paymaster” or “AA31/AA33”
  • Sponsored transactions fail
Causes:
  • Gas Tank has insufficient balance
  • API key is invalid or doesn’t include the network
  • Paymaster is not configured for the network
Solutions:
  1. Check your Gas Tank balance in the Gelato App
  2. Verify your API key includes the target network
  3. Ensure you’re using the correct API key for sponsored payments

3. Insufficient Funds for Gas

Symptoms:
  • Error contains “insufficient funds”
  • Native or ERC-20 payment fails
Causes:
  • User doesn’t have enough native tokens
  • User doesn’t have enough ERC-20 tokens for gas payment
  • Account is not deployed yet
Solutions:

4. Account Not Deployed

Symptoms:
  • Error contains “AA25” or nonce-related errors
  • First transaction fails
Causes:
  • Smart account hasn’t been deployed yet
  • Using wrong account address
Solutions:

5. Invalid Signature

Symptoms:
  • Error contains “AA21” or “AA24”
  • Signature validation fails
Causes:
  • Wrong private key
  • Wrong chain ID
  • Signature expired
Solutions:

6. Transaction Pending Forever

Symptoms:
  • Transaction submitted but never confirms
  • wait() never resolves
Causes:
  • Network congestion
  • Bundler mempool issues
  • Low gas price
Solutions:

Debugging Tips

1. Enable Verbose Logging

2. Use Gas Estimation

3. Check Network Support

Before deploying, verify your network is supported:

4. Verify API Key Configuration

  1. Go to Gelato App
  2. Navigate to Paymaster & Bundler > API Keys
  3. Verify the API key includes your target network
  4. Check the API key type (sponsor vs. non-sponsor)

Getting Help

If you’re still experiencing issues:
  1. Review the API Endpoints documentation
  2. Report issues on GitHub

Additional Resources