Gas required exceeds allowance: cause and fix

Where does it stop?

The error comes from the gas estimate, before the transaction is signed and sent. Clients estimate gas for you when you leave it out, so a send can fail here too: no hash, no block, no gas spent.

What does the number mean?

The estimate first runs your call at the highest gas it can allow. In geth’s estimator, that ceiling starts at the block’s gas limit, or at the gas you passed. It is lowered to what the balance, minus the value, can pay at the fee you gave, and to the node’s RPC gas cap. On chains with EIP-7825, geth also caps it at 16,777,216, the most one transaction may use. If the call runs out of gas even there, the estimate returns the ceiling in the error.

So read the number before anything else:

• 0, or very low: the balance is the limit. The account can’t pay for the gas at that fee.
• The block’s gas limit, 16,777,216 or the node’s cap: the call needs more gas than any transaction may use. It usually never finishes, such as a loop that doesn’t end.
• The gas value you set: your limit is too low for this call.

Which ceiling is my number?

Compare it with the chain. On the public Base Sepolia RPC on 2026-10-21, read-only estimates gave:

Read the block’s limit and check the error against it:

import type { PublicClient } from 'viem';

declare const client: PublicClient;
declare const allowance: bigint; // the number in the error

const { gasLimit } = await client.getBlock();
if (allowance === 0n) console.log('the account has no funds for gas on this network');
else if (allowance === 16_777_216n || allowance === gasLimit) console.log('the call needs more gas than one transaction may use: an endless loop, or work too big for one transaction');
else console.log('a lower cap: your gas value, the balance at this fee, or the node\'s own cap');

The wording differs by node. The public Base Sepolia RPC printed “gas required exceeds allowance (0)” for the empty account. For the endless call, it printed “out of gas: gas required exceeds: 16777216”.

Why does it happen?

• The account is empty on that chain. On geth and Anvil, an estimate that carries a fee, such as maxFeePerGas, gets an allowance of 0. Some nodes still return 21,000 for a plain transfer, as the public Base Sepolia RPC did.
• The wallet is on another network. In a dApp, the wallet estimates for you. Allowance 0 there usually means the connected account has no funds on the network the wallet has selected.
• The call never ends. A loop without an exit, or a contract that burns all the gas it is given.
• The gas limit you passed is too low for what the call does.

How do I fix it?

1. If the number is 0, fund the account on the chain you send to. getBalance shows what the node sees.
2. If the number is 16,777,216 or the block limit, find out why the call doesn’t end. Simulate it with simulateContract or call, and check the contract.
3. If the number is your own limit, raise it or leave gas out, so the client estimates it.
4. In an agent, check the balance before the tool estimates, and tell the model “no funds” instead of passing on an error that says reverted.

import type { Address, PublicClient } from 'viem';

declare const client: PublicClient;
declare const from: Address;

const balance = await client.getBalance({ address: from });
if (balance === 0n) throw new Error(`${from} has no funds on this chain: the gas estimate would fail with allowance 0`);

What does it look like in a trace?

The estimate runs inside the send, so it is the send span that fails, with no hash:

error.type says reverted, but no hash means nothing reached the chain. An execution reverted that was mined has a hash and a confirm span. An out of gas on the chain has a receipt with status reverted.