⚠️ Bundler & Paymaster — Error Reference

Complete reference of all ERC-4337 error codes from the EntryPoint contract (v0.6), the bundler, and the paymaster.

Account Errors (AA1x)

Errors related to account creation and initCode execution.

Code Name Description Resolution
AA10 Sender already constructed initCode was provided but the account already exists on-chain. Remove initCode from the UserOp — the account is already deployed.
AA13 initCode failed or OOG The factory's initCode reverted or ran out of gas. Check factory address, initCode calldata. Increase verificationGasLimit.
AA14 initCode must return sender initCode executed but did not create a contract at the expected sender address. Ensure setup() calldata matches deterministic address. Avoid delegatecall in setup.
AA15 initCode must create sender initCode completed but no contract code at sender address. Verify factory deployment logic and salt/nonce parameters.

Account Validation Errors (AA2x)

Errors during validateUserOp — signature verification, nonce, gas, and account state.

Code Name Description Resolution
AA20 Account not deployed No initCode provided but the account does not exist on-chain. Include initCode in the UserOp to deploy the account, or verify the sender address.
AA21 Didn't pay prefund Account doesn't have enough ETH to cover the required prefund. Ensure paymasterAndData is set (paymaster covers prefund). Without paymaster, fund the account.
AA22 Expired or not due UserOp validAfter/validUntil is expired or not yet valid. Retry with a fresh UserOp. Check system clock synchronization.
AA23 Reverted (or OOG) Account's validateUserOp reverted or ran out of gas. Check signature format/encoding. For Safe wallets, verify WebAuthn signature. Increase verificationGasLimit.
AA24 Signature error Account validation returned an invalid signature indicator. Check passkey signature, credential ID, public key coordinates (x, y), and rpId.
AA25 Invalid account nonce UserOp nonce doesn't match the account's current nonce in EntryPoint. Fetch current nonce via getNonce() and rebuild. Often caused by a pending UserOp.

Paymaster Errors (AA3x)

Errors from the paymaster contract during validatePaymasterUserOp.

Code Name Description Resolution
AA30 Paymaster not deployed paymasterAndData references a paymaster that doesn't exist on this chain. Verify paymaster address and target chain.
AA31 Paymaster deposit too low Paymaster doesn't have enough ETH staked in EntryPoint. Infrastructure: fund the paymaster contract. Contact IBEx support if persistent.
AA32 Paymaster expired or not due Paymaster validity window has expired. IBEx auto-handles this with re-sponsor safety net. Otherwise, retry intent.
AA33 Reverted Paymaster's validatePaymasterUserOp reverted. Gas cost exceeds paymaster limit. Retry with a new intent (fresh gas estimation). Consider splitting complex operations.
AA34 Signature error Paymaster returned an invalid signature. paymasterAndData was tampered with or gas values changed after sponsorship. Retry intent.

Execution Errors (AA4x–AA5x)

Errors during on-chain execution of the UserOp calldata and postOp.

Code Name Description Resolution
AA40 Over verificationGasLimit Inner call verification exceeded the gas limit. Increase verificationGasLimit and retry.
AA41 Too little verificationGas Not enough gas allocated for the postOp call. Increase verificationGasLimit.
AA50 postOp reverted The paymaster's postOp function reverted after execution. Check paymaster postOp logic. Ensure the paymaster has enough deposit to cover the actual gas cost.
AA51 Prefund below actualGasCost The actual gas cost exceeded the prefund amount. Increase gas limits in the intent phase to ensure adequate prefund.

EntryPoint Internal Errors (AA9x)

Internal EntryPoint errors — typically infrastructure-level, not caused by user operations.

Code Name Description Resolution
AA90 Invalid beneficiary The beneficiary address (where refunds are sent) is invalid (zero address). Infrastructure: verify bundler configuration.
AA91 Failed send to beneficiary ETH transfer to the beneficiary address failed. Infrastructure: ensure the beneficiary can receive ETH (not a contract that rejects transfers).
AA92 Internal call only A function was called that is restricted to internal EntryPoint use only. Do not call internal EntryPoint functions directly.
AA93 Invalid paymasterAndData The paymasterAndData field is malformed (too short or invalid format). Ensure paymasterAndData is at least 20 bytes (paymaster address) or empty (0x).
AA94 Gas values overflow Gas values in the UserOp cause an arithmetic overflow. Reduce gas limit values. Ensure they fit within uint256 bounds.
AA95 Out of gas The entire transaction ran out of gas before completing EntryPoint processing. Increase the transaction gas limit. This is different from UserOp gas limits.
AA96 Invalid aggregator The UserOp references a signature aggregator that is not valid. IBEx doesn't use signature aggregators. If encountered, file a bug report.

JSON-RPC Bundler Errors

Standard ERC-4337 JSON-RPC error codes returned by the bundler.

Code Name Description Resolution
-32500 Rejected by EP or account EntryPoint or account rejected the UserOp during simulation. Check the full error message for the underlying AA error code.
-32501 Rejected by paymaster Paymaster rejected the UserOp during simulation. Verify paymaster configuration and sponsorship eligibility.
-32502 Opcode violation UserOp uses forbidden opcodes during validation (TIMESTAMP, BLOCKHASH…). Contract-level issue — account or paymaster uses restricted opcodes.
-32503 Expires too soon UserOp validity window is too short for the bundler. Re-sponsor with a longer validity window.
-32504 Entity throttled/banned Account, paymaster, or factory has been throttled or banned by the bundler. Wait and retry. If persistent, contact IBEx support.
-32505 Stake too low Paymaster or factory doesn't have enough stake in EntryPoint. Infrastructure: increase paymaster stake.
-32506 Unsupported aggregator UserOp uses a signature aggregator the bundler doesn't support. IBEx doesn't use aggregators. File a bug report if encountered.
-32507 Invalid paymaster signature paymasterAndData signature invalid — gas values changed between sponsor and execute. IBEx auto-handles with re-sponsor safety net. Otherwise, retry full intent/execute flow.

Safe-Specific Errors

Errors from Safe{Wallet} smart contract logic.

Code Name Description Resolution
GS026 Invalid owner provided Owner address is zero or the sentinel address. Use valid non-zero Ethereum addresses as owners.
GS200 Module already enabled Attempting to enable a module that is already active. Check isModuleEnabled() before enableModule().
GS203 Owner cannot be self setupOwners() rejects an owner equal to address(this). Common with EIP-7702 where the EOA is the Safe. Use a different address as owner (e.g., passkey-derived address).

See Also