ERC-4337 Paymaster Troubleshooting

Use this guide when a MegaFuel-sponsored UserOperation is rejected, remains pending, or completes unexpectedly.

First collect these facts

For every issue, capture:

• environment and chain ID;
• EntryPoint address and ERC-4337 version;
• smart-account sender address and UserOperation nonce;
• UserOperation hash, if submission succeeded;
• JSON-RPC method, timestamp, full error code/message, and HTTP status;
• outer transaction hash and receipt, if available; and
• policy UUID for the sponsor team only.

Never include a private key, seed phrase, API key, or signing secret in a support ticket. Redact signatures if your internal incident process requires it.

Paymaster rejects pm_getPaymasterData

not sponsorable: no matching sponsor policy

Usually one of the policy conditions is not satisfied.

Check that the policy is:

• public, active, and within its validity period;
• on the same BSC chain as the UserOperation;
• set to enable4337: true;
• funded with positive remainingBalance; and
• configured for the smart-account sender and the inner target/method/ receiver, not the outer EntryPoint transaction.

For executeBatch, every inner call must match the same policy.

callData not decodable (unsupported account type)

MegaFuel cannot safely determine the contract call that the smart account would execute. The current decoder supports standard SimpleAccount execute and executeBatch encodings. Use a supported encoding or arrange wallet ABI compatibility validation before attempting sponsorship.

Gas price or gas limit exceeds a sponsor cap

The wallet controls maxFeePerGas and UserOperation gas limits, so MegaFuel enforces service-side safety ceilings in addition to policy spending limits.

• Fetch current network fee data and choose a reasonable maxFeePerGas / maxPriorityFeePerGas pair.
• Ensure maxPriorityFeePerGas does not exceed maxFeePerGas.
• Do not inflate callGasLimit, verificationGasLimit, or preVerificationGas; obtain an estimate from the Bundler and use it.
• If the intended application call genuinely needs more gas than the product safety ceiling, contact MegaFuel with a testnet reproduction and expected cost profile.

Final paymaster data expired or signature validation fails

Final paymaster data has a short validity window and is bound to the operation. Restart from gas estimation and pm_getPaymasterData when:

• time has elapsed before submission;
• any gas, nonce, call, factory, or fee field changed;
• a different account signature was produced over a changed UserOperation hash; or
• the wallet accidentally mixed an EntryPoint version or chain ID.

Bundler rejects eth_sendUserOperation

Unsupported EntryPoint or non-MegaFuel paymaster

Call eth_supportedEntryPoints on the exact Bundler endpoint. Use a returned EntryPoint and the paymaster address returned by MegaFuel's final paymaster RPC. The MegaFuel Bundler is sponsor-gated and intentionally rejects third-party or self-funded paymasters.

Account signature, nonce, or validation error

Validate all of the following together:

• the UserOperation hash was computed using the selected EntryPoint version;
• the account's signing scheme matches its validateUserOp implementation;
• counterfactual account factory data derives the stated sender;
• the nonce belongs to that (EntryPoint, smart account, nonceKey) lane; and
• final paymaster fields are exactly those returned by pm_getPaymasterData.

For v0.6, verify that the Bundler request uses initCode and the correct classic paymasterAndData layout. For v0.7/v0.8, use the separate packed-family JSON fields.

Same-nonce conflict or stale nonce

An ERC-4337 UserOperation nonce is not an EOA transaction nonce. It has a nonceKey and a 64-bit sequence, and is scoped by EntryPoint and smart account.

For a sequential wallet flow:

1. query nr_getPendingUserOperationNonce(entryPoint, sender, nonceKey);
2. build and sign the UserOperation promptly; and
3. if submission returns a collision, stale nonce, or replacement error, re-query, rebuild, and re-sign.

The nonce query is a snapshot. It cannot reserve a nonce against another client that submits in the meantime.

Submitted UserOperation is pending

eth_sendUserOperation returns an accepted UserOperation hash; it is not proof of on-chain inclusion. Poll eth_getUserOperationReceipt using that hash.

While pending:

• eth_getUserOperationReceipt can return null;
• eth_getUserOperationByHash can show the stored operation and, if available, an outer transaction attempt; and
• resending identical UserOperation content is idempotent, but changing a signed operation requires a new paymaster authorization and account signature.

Do not create multiple unrelated operations with the same nonce unless your wallet deliberately implements ERC-4337 replacement behavior and handles the resulting replacement rules.

Receipt says success: false

This means the UserOperation was processed but its account call was unsuccessful. It is different from a missing receipt or an outer transaction that never executed the operation.

Inspect:

1. the transactionHash from the UserOperation receipt;
2. the on-chain transaction receipt and logs; and
3. the target contract call encoded inside the account's callData.

The policy can be correctly charged for actual work even when the application call fails, depending on EntryPoint execution and paymaster settlement. Treat the UserOperation receipt and the policy's post-operation accounting as the authoritative records.

Policy accounting does not look right

Read the policy using pm_getPolicyByUuid and compare:

• sponsoredGasfee before and after;
• remainingBalance before and after; and
• actualGasCost in the UserOperation receipt.

For a successfully settled operation, policy sponsored gas fee increases and remaining balance decreases by the actual gas cost in wei. Indexing is asynchronous; allow a short confirmation/indexing interval before escalating.

Escalation template

Environment / chain ID:
EntryPoint version and address:
Smart-account sender:
Nonce / nonceKey:
UserOperation hash:
Outer transaction hash (if any):
UTC timestamp:
RPC method and error:
Policy UUID (share only through approved support channel):
Expected application call:

Include a redacted UserOperation only when requested through an approved support channel. Do not include secrets.