Ethereum Transaction Errors Explained: What Each Message Means and How to Fix It

1. Where do these error messages come from?

Almost every wallet, library and RPC provider passes through the error text produced by go-ethereum, the most widely run Ethereum client, and the clients of the Layer 2 networks reuse the same strings. MetaMask wraps them in its own dialog, ethers.js adds a code such as NONCE_EXPIRED or REPLACEMENT_UNDERPRICED, and an RPC provider returns them as a JSON-RPC error with code -32000. Underneath, the message is the same.

The node runs two different sets of checks. The first happens when it receives the transaction: is the nonce right, is the fee acceptable, is the gas limit sane, can the sender pay. A transaction that fails here is dropped and nothing is recorded on-chain. The second happens when the transaction is executed inside a block: does the contract code complete within the gas limit without reverting. A transaction that fails here is still mined, with status Fail on the explorer, and the fee is spent.

Knowing which family an error belongs to tells you two things at once: whether you lost money, and whether the fix is on your side (the transaction) or on the contract's side (the inputs).

2. Quick reference: every common error

The exact strings, in the order you are most likely to meet them. The wording is from the go-ethereum source; wallets sometimes shorten it.

3. What does "nonce too low" mean?

Every account numbers its transactions from zero, and each number can be used once. "Nonce too low" means the transaction you just sent carries a number the network has already confirmed for that account. The node compares the nonce in your transaction with the account's next expected nonce and refuses anything below it.

It happens when the wallet's idea of the next nonce is stale: a transaction was sent from the same account in another wallet or device, a speed-up or cancel already took the number, or a local development chain was restarted so the account's counter went back to zero while MetaMask kept counting. On a hardware wallet it also shows up when a transaction is signed twice.

The fix is to let the wallet resync. Look the address up on the explorer first: if the thing you were trying to do already went through under that nonce, do not resend. If the wallet keeps offering a stale number, MetaMask's "Delete activity and nonce data" option (Settings, Developer tools) clears the local counter for the current network. MetaMask notes it is irreversible, affects only the current network and does not touch your balance. In code, read the next nonce with eth_getTransactionCount using the "pending" tag before signing instead of keeping your own counter.

4. What does "nonce too high" mean?

The opposite gap. The transaction's nonce is above the account's next expected value, so there is a hole: a lower number has not been confirmed yet. Nodes hold such a transaction in a queue rather than executing it, and some reject it outright with this message.

Typical cause: a batch of transactions where an earlier one was dropped, or a local chain reset in the other direction (the chain was reset but the wallet was not, so the wallet sends nonce 40 to a chain expecting nonce 0). Fill the gap by sending the missing nonce, or clear the wallet's activity data as above.

5. What does "replacement transaction underpriced" mean?

You tried to replace a pending transaction (speed up, cancel, or simply resend with the same nonce) and the new one does not pay enough more than the old one. The node will only swap a pending transaction for another with the same nonce if the fee rises by a minimum percentage; in go-ethereum that price bump defaults to 10 percent, and it applies to both the max fee and the priority fee.

The nonce is correct; the price is the problem. Bump both fee fields by at least 10 percent over the pending transaction, not over the current network rate. MetaMask's own guidance for the related "transaction underpriced" dialog is a priority fee at least 10 percent higher and a max fee at least 30 percent higher. To cancel instead, send 0 ETH to your own address with the same nonce and the bumped fee, as described in MetaMask's error guide. Either way the replacement gets a new transaction hash and the old one is dropped.

6. What does "transaction underpriced" mean?

Without the word "replacement", this is a plain price check: the fee on your transaction is below what the node is willing to hold in its pool. Nodes set a minimum gas price to keep spam out, and during a busy period a wallet's "low" fee estimate can land under it. The sibling message "transaction gas price below minimum" means the same thing.

Raise the max fee and the priority fee and resend. Nothing was recorded on-chain, so there is no stuck transaction to clear. If you see it repeatedly on one network, that network's minimum is higher than your wallet's default; the per-network pages of the gas tracker show the going rate.

7. What does "insufficient funds for gas * price + value" mean?

The sender's balance in the native coin must cover the amount being sent plus the worst-case fee, which is the gas limit multiplied by the max fee per gas. That rule is written into EIP-1559: the signer must be able to afford gas_limit times max_fee_per_gas, on top of the value. The node checks it against the maximum, not against what the transaction will actually cost, so a transaction can fail this check even though the eventual fee would have fit.

Three causes cover almost every case. You hold tokens but no native coin: USDC on Base needs ETH for gas, USDT on Polygon needs POL, anything on BNB Smart Chain needs BNB. You are sending your entire balance and left nothing for the fee: subtract the maximum fee first. Or the gas limit is inflated by a contract call, so the worst case is far above the real cost.

Fix: top up the native coin, send a smaller amount, or lower the max fee or gas limit if they are padded. The related "insufficient funds for transfer" means the value alone exceeds the balance, before gas is even considered.

8. Intrinsic gas too low, out of gas and gas limit errors

Four messages concern the gas limit, and they fail at different moments. "Intrinsic gas too low" is a pre-inclusion rejection: every transaction has a fixed base cost before any code runs, 21,000 gas for a plain transfer plus a charge per byte of data, and your gas limit is below it. The ethereum.org gas documentation puts the standard transfer at 21,000 units; a token transfer or contract call needs more. Raise the limit, or let the wallet or library estimate it.

"Out of gas" is the post-inclusion version. The limit covered the base cost, the transaction was mined, and the contract code then needed more than the limit allowed. The EVM reverts every state change but, as the same documentation says, all the gas provided is still consumed for the work performed. The fee is gone and the transaction shows as failed on the explorer. Resend with a higher limit; wallets usually add a margin over the estimate for this reason.

"Exceeds block gas limit" means the limit you set is larger than an entire block may hold on that network. "Transaction gas limit too high" is newer: since EIP-7825 a single transaction may not request more than 16,777,216 gas (2 to the power of 24), and a transaction above the cap is rejected. Both are fixed by lowering the limit; a legitimate transaction never needs anything close to those numbers.

9. Max fee and priority fee errors

Since EIP-1559 a transaction carries two fee fields: the max fee per gas, which is the most you will pay per unit, and the max priority fee per gas, the tip for the validator. The protocol enforces two relationships between them and the block's base fee, and each has its own error.

"Max fee per gas less than block base fee": your max fee is below the current base fee, so the transaction cannot be included at any tip. This hits transactions signed during a quiet period and broadcast after the base fee rose, and transactions built with a hard-coded fee. Raise the max fee, or wait: the base fee moves block by block and the transaction becomes valid again if it falls below your cap.

"Max priority fee per gas higher than max fee per gas": the tip exceeds the total cap, which the specification forbids because the base fee is filled first and the tip can only come from what remains. Set the priority fee at or below the max fee. A correctly built transaction has max fee equal to roughly twice the base fee plus the tip, which leaves room for the base fee to rise while it waits.

10. What does "execution reverted" mean?

The contract you called stopped execution on purpose. Solidity's require, revert and assert statements all end in this message, often followed by the contract's own reason string: "ERC20: transfer amount exceeds allowance", "UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT", "Pausable: paused" and so on. When the reason is empty, you see only "execution reverted" or the raw error data.

Most of the time you see it before sending, because the wallet runs the call through eth_estimateGas and the simulation reverts; MetaMask then reports that it cannot estimate gas. That is the cheap version: nothing was sent. The expensive version is a transaction that passed simulation, was mined, and reverted on-chain because the state changed in between (a swap price moved past your slippage, someone else bought the last item, a deadline passed). It shows as Fail on the explorer and the fee is paid.

The fix is never a higher gas limit. Read the reason string, then change the inputs: approve the token first, widen slippage or lower the amount, check that the contract is not paused, and confirm you are on the network the contract lives on. The explorer's transaction page shows the revert reason for mined failures; the Etherscan guide shows where to find it.

11. Already known, invalid sender and oversized data

"Already known" is not an error in any practical sense. The node already holds the exact transaction you sent, usually because a library retried a broadcast or two wallets pushed the same signed bytes. Wait for the original to confirm.

"Invalid sender" means the node could not recover a valid signer from the signature. Since EIP-155 the chain ID is part of what gets signed, so a transaction signed for chain 1 and sent to chain 137 recovers to garbage and is refused. Check the chain ID in the signing configuration against what the RPC endpoint reports; the chain ID list covers the numbers and the mismatch case.

"Oversized data" means the transaction's byte size is above what the node accepts into its pool, which only happens with very large contract deployments or calldata. Split the data, or deploy through a factory.

12. Does a failed transaction cost gas?

It depends on where it failed. Everything in the first family of this guide (nonce, underpriced, insufficient funds, intrinsic gas, fee cap, already known, invalid sender, oversized data) is a rejection: the node dropped the transaction and no block contains it, so no fee was charged and there is nothing to find on the explorer. Resending costs nothing extra.

"Out of gas" and a mined "execution reverted" are the second family: the transaction is in a block with status Fail, the validator did the work, and the fee is paid in full. The ethereum.org documentation is explicit that the fee is paid regardless of whether a transaction succeeds or fails. Any ETH or tokens you tried to move stay where they were; only the fee is lost.

13. How to avoid these errors in code

Four habits remove most of this list from a sending service: read the pending nonce from the node instead of keeping a counter, take fee estimates from the node for the network you are on, estimate gas before signing and add a margin, and check the balance against amount plus worst-case fee before broadcasting. The ChainGate SDK does all four inside transfer(), and surfaces the one case you have to handle yourself as a typed error:

import { ChainGate, importWallet, NotEnoughFundsError } from 'chaingate';

const cg = new ChainGate({ apiKey: process.env.CHAINGATE_API_KEY });
const wallet = importWallet({ phrase: process.env.MNEMONIC });
const eth = cg.connect(cg.networks.ethereum, wallet);

try {
  // Nonce, gas limit and EIP-1559 fees are read from the node for you
  const tx = await eth.transfer(cg.networks.ethereum.amount('0.05'), '0x...');
  tx.setFee(tx.recommendedFees().normal);

  if (!tx.enoughFunds()) {
    // amount + worst-case fee exceeds the balance: nothing is broadcast
    console.log('short by', tx.missingFunds());
    return;
  }

  const sent = await tx.signAndBroadcast();
  console.log(sent.transactionId);
} catch (err) {
  if (err instanceof NotEnoughFundsError) {
    console.error('Not enough ETH for amount + fee');
  }
  throw err;
}

The tutorial on sending crypto in JavaScript shows the full flow for Ethereum and the UTXO chains, and the transfer documentation lists the fee tiers and the missingFunds field that tells you exactly how much native coin is short.

14. Where to go from here

Most of these errors are about fees, so the next page to read is what gas fees are and how max fee, priority fee and base fee fit together, followed by the gas tracker for the rates on each network right now. If a transaction did go out and you need to find out what happened to it, the transaction hash guide shows how to look it up. And for a TypeScript library that handles nonces, fees and balance checks across Ethereum, the EVM Layer 2s and Bitcoin, ChainGate is the SDK behind this site.

Frequently asked questions