Troubleshooting

Here are helpful resources for debugging issues you may encounter while using thirdweb Engine.

What it means

The RPC reported that this transaction failed simulation and is expected to fail onchain, and it is being rejected before it is sent. No gas is consumed. This error indicates the contract logic will throw an error (or "revert the execution").

Common reasons: minting from a token contract that has no claim condition, has not started the minting period, is out of supply, has the incorrect amount paid to it, the calling backend wallet does not have permissions to call the contract.

How to resolve

Try to simulate the transaction by passing the ?simulateTx=true query parameter or using the thirdweb Transaction Simulator to reveal the error message.

Also known as: execution reverted

What it means

The transaction passed simulation but the execution was reverted onchain. This can occur if a change in state occurred, such as an NFT contract running out of supply before a transaction was mined.

Another common reason is the transaction ran out of gas. You can verify this by checking the "More Details" section in your blockchain explorer and confirming if the gas usage reached the gas limit:

How to resolve

If the transaction failed due to onchain logic, try to simulate the transaction (see above) to identify the reason.

If the gas limit was reached, you may try manually overriding the gas settings. Engine automatically estimates the gas limit through simulation, and it is not recommended to override the gas limit unless the estimation is incorrect.

Also known as: REPLACEMENT_UNDERPRICED, already known

What it means

Engine has already submitted this or another transaction with the same nonce. That transaction is in mempool and waiting to be mined by the chain.

Engine automatically manages nonces so this error typically should not occur.

How to resolve

It's possible the transactions are not being accepted by the mempool. To remediate this issue, you can retry a transaction, cancel it, or reset all backend wallet nonces.

To retry a transaction, use POST /transaction/sync-retry and provide the queueId. You may also provide a higher gas value to increase the likelihood of the transaction being mined.

To cancel a transaction, use POST /transaction/cancel and provide the queueId.

To reset the nonce for all backend wallets, use POST /backend-wallet/reset-nonce to force-sync the Engine nonces with the onchain values.

Also known as: Insufficient funds for intrinsic transaction cost

What it means

Your backend wallet has insufficient funds to complete the transaction.

Note that on EVM blockchains, a transaction must place a gas fee bid on a transaction that is higher than the amount that will actually get consumed. This means your wallet must have a minimum amount of gas in order to send transactions.

You can estimate how much gas is needed. Adjust the values to your use case and chain.

• gas ("gas limit"): The unit of gas that a transaction needs to complete. Assume an NFT mint that takes 120,000 gas.
• maxFeePerGas: The maximum amount of native token to bid, per gas. Assume 50 gwei.
• Amount of gas needed = 6,000,000,000,000,000 wei. Assume the native currency is ETH which has 18 decimals, this equals 0.006 ETH.

Even though the transaction is expected to consume less gas, the transaction will fail unless the wallet holds at least this much native gas currency.

How to resolve

Add more funds to your backend wallet. Or wait until the gas fees on the chain are lower and try again.

UserOps are User Operations sent by a backend wallet on behalf of smart accounts, used in the Account Abstraction pattern.

Also known as: code -32507

What it means

The backend wallet you are sending the transaction with does not have sufficient permissions to send a userOp for this account address.

How to resolve

Confirm if the backend wallet is a valid admin for this account. If you are using Session Keys, confirm they are not close to or already expired.

What it means

Your thirdweb API key used by Engine is not properly configured to use Account Abstraction, or you have a sponsorship rule that has been exceeded.

How to resolve

Confirm if the API key is tied to an account with valid payment. Also confirm if there are any sponsorship rule for the Engine API key.