Skip to content
PenyuOnCore
Menu
  • Home
  • Core Ecosystem Analysis
  • Personal Finance & Investing
  • Make Money Online
  • Bitcoin
  • About Us
Menu
ERC20 insufficient allowance error explained: how to fix it in OpenZeppelin v4 and v5

“ERC20: insufficient allowance” Error: What It Means and How to Fix It (OpenZeppelin v4 & v5)

Posted on November 17, 2026

Quick answer: “ERC20: insufficient allowance” means a contract (or address) tried to move your tokens with transferFrom, but the token owner had not approved that spender for at least that amount. Fix it by calling approve(spender, amount) on the token contract from the owner’s address first, or by using transfer if the owner is sending their own tokens. If you see “ERC20: transfer amount exceeds balance” instead, the approval is fine but the sender’s balance is too low.

Both messages come from OpenZeppelin’s ERC-20 implementation, which most tokens on Ethereum, Base, Core and other EVM chains are built on. In OpenZeppelin Contracts v5, the same failures show up as the custom errors ERC20InsufficientAllowance and ERC20InsufficientBalance. That change is why many developers see “unknown custom error” where an old tutorial shows a readable string. This guide covers both versions, how to decode the error, and the fixes that work.

What the error actually means

The ERC-20 standard has two ways to move tokens:

  • transfer(to, amount) moves tokens from the caller’s own balance. No approval is needed.
  • transferFrom(from, to, amount) lets a spender move tokens out of someone else’s balance. It only works if from has called approve(spender, amount) first.

When a DEX, staking vault, or your own contract calls transferFrom, OpenZeppelin’s internal _spendAllowance function checks allowance(owner, spender). In v4.9.6 the check is require(currentAllowance >= amount, "ERC20: insufficient allowance"). In v5.6.1 it is revert ERC20InsufficientAllowance(spender, currentAllowance, value). In both versions, an allowance of type(uint256).max counts as unlimited and is never reduced.

Note that the spender is whichever address calls transferFrom, which is usually the contract you’re interacting with, not your wallet. Approving the wrong address is the most common cause of this error.

OpenZeppelin v4 vs v5: what you’ll see

OpenZeppelin’s v5.0 changelog says the library “replaced revert strings and require statements with custom errors”. The ERC-20 errors follow ERC-6093: Custom errors for commonly-used tokens. We compiled the same token and a minimal vault against v4.9.6 and v5.6.1 and ran them with Foundry 1.9.0. These are the exact reverts we got:

SituationOpenZeppelin v4.xOpenZeppelin v5.xSelector (v5)
No or too little approvalERC20: insufficient allowanceERC20InsufficientAllowance(spender, allowance, needed)0xfb8f41b2
Balance lower than amountERC20: transfer amount exceeds balanceERC20InsufficientBalance(sender, balance, needed)0xe450d38c

With v5 the error is more useful, because it tells you the spender address, the current allowance, and the amount needed. For example, a test with no approval failed with ERC20InsufficientAllowance(0x2e23…470b, 0, 1000000000000000000). That means an allowance of 0 against 1 token with 18 decimals. A partial approval showed 500000000000000000 (0.5 token) against the same 1e18 needed.

Also note: when the vault had an unlimited approval but the user tried to deposit 200 tokens while holding 100, the revert was the balance error, not the allowance error. The allowance check passes first, then the balance check fails. If your allowance looks right, check your balance and decimals next.

Checklist for fixing the ERC20 insufficient allowance error: right token, right spender, enough amount, correct decimals, balance check

How to decode “unknown custom error” (v5 tokens)

If the contract you call doesn’t include the token’s errors in its ABI, ethers.js v6 can’t name the error. With ethers 6.17.0 against a local Anvil node, the call failed with code: CALL_EXCEPTION and shortMessage: 'execution reverted (unknown custom error)'. The node’s own message was execution reverted: custom error 0xfb8f41b2: …. The raw revert data is still in error.data, so you can decode it yourself:

With ethers.js v6

try {
  await vault.deposit(tokenAddress, amount);
} catch (e) {
  // token = new ethers.Contract(tokenAddress, tokenAbi, signer)
  const parsed = token.interface.parseError(e.data);
  console.log(parsed.name, parsed.args); // ERC20InsufficientAllowance [spender, allowance, needed]
}

Interface.parseError works with any ABI that contains the error definition. You can use the full OpenZeppelin ERC20 artifact or just the two error fragments.

With Foundry’s cast

cast decode-error 0xfb8f41b2000000...0de0b6b3a7640000
# ERC20InsufficientAllowance(address,uint256,uint256)
# 0xe7f1...0512
# 0
# 1000000000000000000 [1e18]

cast decode-error found the signature from the selector alone in our test. You can also pass --sig "ERC20InsufficientAllowance(address,uint256,uint256)" to skip the lookup. In forge test -vvv, the trace already shows the decoded error name and arguments.

For a broader walkthrough of revert reasons, see our guide to the “execution reverted” error.

How to fix “ERC20: insufficient allowance”

1. Approve the correct spender on the correct token

Call approve on the token contract, from the owner wallet, with the contract that will call transferFrom as the spender. In ethers v6:

await (await token.approve(vaultAddress, amount)).wait();
await (await vault.deposit(tokenAddress, amount)).wait();

A common mistake is calling approve from inside your own contract (for example token.approve(address(this), x)). That sets the allowance for your contract’s own balance, not the user’s. The user must approve directly, from their wallet.

2. Use transfer when the owner is the caller

If your contract is moving tokens it already holds, call transfer(to, amount) instead of transferFrom(address(this), to, amount). No allowance is involved.

3. Approve enough, in base units

Allowances are raw integers. A token with 6 decimals needs parseUnits("100", 6), not parseEther("100"). If the amount is off by a factor of 1012, check decimals first. Also remember that every transferFrom reduces a finite allowance. An approval that worked for the first deposit may be used up by the second.

4. Wait for the approval to be mined

Sending the spend before the approval is mined fails on the old state. In scripts, await tx.wait() on the approval first. There is one more ethers v6 detail: its AbstractProvider shares identical requests made within the same 250 ms window. In our local test, retrying the exact same call right after a failed attempt and a fast Anvil approval returned the stale revert again, even though allowance() already showed the new value. Sending the same transaction with cast send succeeded. If an immediate retry fails “for no reason”, re-read the allowance and try again a moment later.

5. Watch for allowance helpers removed in v5

OpenZeppelin v5 removed the non-standard increaseAllowance and decreaseAllowance functions from ERC20, according to the changelog. Calling them on a v5 token will fail. For contract-to-contract approvals, the library’s SafeERC20 provides safeIncreaseAllowance and forceApprove. The changelog notes these were refactored “to support USDT-like tokens”.

How to fix “ERC20: transfer amount exceeds balance”

  • Check balanceOf(sender) on the same token address and chain. Bridged tokens with the same symbol often have different contracts, as with the USDT and USDC variants on Core.
  • Check decimals, as above.
  • For fee-on-transfer or rebasing tokens, the amount that arrives can be lower than the amount sent. Code that forwards the “expected” amount can then exceed the contract’s real balance.
  • In v5, read the balance and needed arguments of ERC20InsufficientBalance. They show exactly how far short you are.

Don’t confuse it with similar errors

“Insufficient allowance” is a token-level revert. It’s different from the node error “gas required exceeds allowance”, which is about the gas limit or your native-coin balance, and from MetaMask’s “insufficient funds for gas”. On Core, the token logic is the same as on any EVM chain. If you’re testing your own token there, our Foundry deployment guide for Core shows the setup.

A safety note on unlimited approvals

Many dApps ask for an unlimited (type(uint256).max) approval so you never hit this error again. That’s convenient, but it lets the spender move any amount of that token as long as the approval stands. Approving only what you need is the more conservative choice for wallets that hold real value. Review and remove old approvals periodically. Our guide on how to revoke token approvals walks through it.

FAQ

Why does approve succeed but transferFrom still fails?

Usually you approved a different spender (your wallet or the wrong contract), approved on a different token address or chain, or approved too few base units. In v5, the error’s first argument shows which spender the token checked.

Is “ERC20InsufficientAllowance” the same error as “ERC20: insufficient allowance”?

Yes. It’s the same check. OpenZeppelin v4 reverts with the string and v5 reverts with the ERC-6093 custom error (selector 0xfb8f41b2).

Do I need to approve before sending tokens to a friend?

No. A plain wallet send uses transfer, which doesn’t use allowances. Approvals are only needed when a contract or another address moves tokens for you.

Does an unlimited approval ever run out?

Not in OpenZeppelin’s implementation. Both v4 and v5 skip the allowance deduction when it equals type(uint256).max. Other token implementations may behave differently.

Disclaimer: This article is for educational purposes only and is not financial or investment advice. Always test on a testnet or local node before sending transactions with real funds.

Recent Posts

  • “Could Not Coalesce Error” in ethers v6: What It Means and How to Fix It
  • “ERC20: insufficient allowance” Error: What It Means and How to Fix It (OpenZeppelin v4 & v5)
  • Can You Still Buy I Bonds With Your Tax Refund? (What Changed in 2025)
  • “Nonce Too High” Error: What It Means and How to Fix It (MetaMask, Hardhat, Foundry)
  • Udemy Instructor Payout Schedule: When You Actually Get Paid
Subscription form is not available at the moment
  • Altcoin News
  • Bitcoin
  • Core Ecosystem Analysis
  • DeFi
  • Free Crypto Signals
  • Make Money Online
  • Personal Finance & Investing
  • Token Analysis
  • About Us
  • Contact
  • Privacy Policy
  • Disclaimer
©2026 PenyuOnCore | Design: Newspaperly WordPress Theme