> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://www.openfort.io/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

# Bundler Errors

This page documents common errors you may encounter when using the bundler, including both bundler-specific errors and EntryPoint errors.

## Bundler Error Codes (EIP-7769)

The bundler implements the [EIP-7769](https://eips.ethereum.org/EIPS/eip-7769) specification which standardizes ERC-4337 bundler error codes.

| Error Code | Description |
|------------|-------------|
| -32602 | Invalid UserOperation struct/fields |
| -32500 | Rejected by EntryPoint's simulateValidation |
| -32501 | Rejected by paymaster's validatePaymasterUserOp |
| -32502 | Violation of ERC-7562 opcode validation rules |
| -32503 | UserOperation out of time-range |
| -32504 | Paymaster throttled or banned by reputation rules |
| -32505 | Paymaster stake or unstake-delay too low |
| -32507 | Wallet signature check failed |
| -32508 | Paymaster balance insufficient for pending operations |
| -32521 | UserOperation execution reverted |
| -32603 | Internal error - bundler failure |

***

## EntryPoint Errors

These errors originate from the EntryPoint contract during UserOperation validation or execution.

### Account Errors (AA1x)

#### AA10: sender already constructed

The account at the `sender` address already exists, but the UserOperation includes initialization code.

**Solutions:**

* Remove the `initCode` (v0.6) or `factory`/`factoryData` (v0.8+) fields if the account is already deployed
* Verify you're using the correct sender address

#### AA13: initCode failed or OOG

The initialization code failed to execute or ran out of gas.

**Solutions:**

* Increase the `verificationGasLimit`
* Verify your `initCode` or `factoryData` is correct
* Check that the factory contract is deployed on this chain

#### AA14: initCode must return sender

The factory's initialization code did not return the expected sender address.

**Solutions:**

* Verify the `sender` address matches what your factory will deploy
* Check your factory contract implementation

#### AA15: initCode must create sender

The initialization code executed but didn't create a contract at the sender address.

**Solutions:**

* Verify the factory contract deploys to the expected address
* Check for issues in your account deployment logic

### Account Validation Errors (AA2x)

#### AA20: account not deployed

The `sender` account does not exist and no initialization code was provided.

**Solutions:**

* Include `initCode` (v0.6) or `factory`/`factoryData` (v0.8+) to deploy the account
* Verify the sender address is correct

#### AA21: didn't pay prefund

The account doesn't have enough native tokens to cover gas costs (when not using a paymaster).

**Solutions:**

* Fund the sender address with native tokens
* Use a paymaster to sponsor the transaction

#### AA22: expired or not due

The UserOperation's validity time window has passed or hasn't started yet.

**Solutions:**

* Check the account's validation time constraints
* Submit the operation within the valid time window

#### AA23: reverted

The account's validation function reverted.

**Solutions:**

* Check your account contract's `validateUserOp` implementation
* Verify the signature is valid
* Ensure the account has proper permissions

#### AA24: signature error

The signature verification failed.

**Solutions:**

* Verify the signature is correctly formatted
* Ensure you're signing the correct UserOperation hash
* Check the signer has permission on the account

#### AA25: invalid account nonce

The nonce is invalid (already used or incorrect key).

**Solutions:**

* Get the current nonce from the EntryPoint contract
* Ensure you're using the correct nonce key for parallel operations

### Paymaster Errors (AA3x)

#### AA30: paymaster not deployed

The paymaster contract specified in the UserOperation is not deployed.

**Solutions:**

* Verify the paymaster address is correct
* Check that the paymaster is deployed on this chain

#### AA31: paymaster deposit too low

The paymaster doesn't have enough funds deposited in the EntryPoint.

**Solutions:**

* Contact your paymaster provider
* If self-hosted, deposit more funds via the paymaster's `deposit()` function

#### AA32: paymaster expired or not due

The paymaster signature has expired or isn't valid yet.

**Solutions:**

* Request fresh paymaster data
* Check the paymaster's time validity window

#### AA33: reverted

The paymaster's validation function reverted.

**Solutions:**

* Contact your paymaster provider
* Verify the UserOperation meets the paymaster's sponsorship criteria

#### AA34: signature error

The paymaster's signature verification failed.

**Solutions:**

* Request fresh paymaster data
* Verify the paymaster data hasn't been tampered with

### Gas Errors (AA4x)

#### AA40: over verificationGasLimit

The verification phase used more gas than allocated.

**Solutions:**

* Increase `verificationGasLimit`
* Re-estimate gas using `eth_estimateUserOperationGas`

#### AA41: too little verificationGas

The `verificationGasLimit` is set too low for the operation.

**Solutions:**

* Increase `verificationGasLimit`
* Use `eth_estimateUserOperationGas` to get accurate estimates

### Post-Operation Errors (AA5x)

#### AA50: postOp reverted

The paymaster's `postOp` function reverted.

**Solutions:**

* Contact your paymaster provider
* Increase `paymasterPostOpGasLimit` if using v0.8+

#### AA51: prefund below actualGasCost

The actual gas cost exceeded what was prefunded.

**Solutions:**

* Increase gas limits
* Ensure sufficient funds or paymaster coverage

### Internal Errors (AA9x)

#### AA90: invalid beneficiary

The bundler specified an invalid beneficiary address.

**Solutions:**

* This is a bundler configuration error; contact support

#### AA91: failed send to beneficiary

Failed to send funds to the bundler's beneficiary address.

**Solutions:**

* This is typically a bundler infrastructure issue; contact support

#### AA92: internal call only

An external call was made to an internal EntryPoint function.

**Solutions:**

* Ensure your code isn't directly calling internal EntryPoint methods

#### AA93: invalid paymasterAndData

The `paymasterAndData` field is malformed.

**Solutions:**

* Verify the paymaster data format (first 20 bytes must be paymaster address)
* Request fresh paymaster data

#### AA94: gas values overflow

Gas values caused an arithmetic overflow.

**Solutions:**

* Reduce gas limit values
* Use reasonable gas estimates

#### AA95: out of gas

The operation ran out of gas during execution.

**Solutions:**

* Increase `callGasLimit`
* Optimize your transaction's gas usage

#### AA96: invalid aggregator

An invalid signature aggregator was specified.

**Solutions:**

* Verify the aggregator contract address
* Ensure the aggregator is properly registered