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, use POST /backend-wallet/reset-nonce to sync the Engine nonce with the onchain value. This step resets all nonce values tracked in Engine, and the next sent transaction will use the next available onchain nonce.

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.