Overview
MetaMask is a widely used software wallet (hot wallet) for interacting with DeFi, dApps, and tokens. Transactions can fail or hang for many reasons — from contract reverts to nonce gaps or hardware-wallet confirmations. This guide explains the common error messages you’ll see (including things like "alert transaction error exception thrown in contract code metamask"), how to diagnose them, and step-by-step fixes I use in daily DeFi work.
Short version: check gas, check nonce, check contract approvals. Then act.
Who this guide is for
- Active DeFi users who send swaps, approvals, or contract calls from MetaMask.
- Mobile-first users who rely on the MetaMask mobile dApp browser. (See mobile setup: /metamask-mobile-ios-android.)
- People using hardware wallets with MetaMask — especially Ledger (see /ledger-with-metamask-guide).
Who should look elsewhere? If you never interact with smart contracts and want cold storage only, a hardware wallet-only routine may be a better fit. But if you need DeFi, this applies.
Quick checklist (before you panic)
- Is the transaction "Pending" in MetaMask? (Yes/no.)
- Open the transaction on a block explorer (/using-etherscan-with-metamask). Does it show "Pending" or "Fail/ Revert"?
- Do you have enough ETH for gas?
- Are you using a hardware wallet (Ledger)? If so, is the Ethereum app open?
And breathe. Small fixes often work.
Common MetaMask transaction errors — what they mean
| Error message (what you might see) |
Likely cause |
Quick fix |
| "alert transaction error exception thrown in contract code metamask" |
Contract execution reverted (require failed, insufficient allowance, or out-of-gas) |
View tx on explorer, decode input, approve token allowance if needed, retry with correct params or higher gas |
| "a wallet connection request is already pending metamask" |
Browser/dApp popup or WalletConnect session waiting for user action |
Close popup, disconnect site (/disconnect-connected-sites), refresh page |
| "can't confirm transaction metamask ledger" |
Ledger app not open, firmware/app mismatch, or contract signing settings |
Open Ethereum app on Ledger, update firmware, enable contract data if required, replug device (see /ledger-errors-and-troubleshooting) |
| "pending transaction metamask" (stuck) |
Low gas, network congestion, or nonce gap |
Speed up/cancel or send replacement tx with same nonce (see steps below) |
How to cancel or replace a pending transaction (step by step)
When a transaction is stuck the chain is waiting for a specific nonce. You can either replace that transaction (same nonce, higher gas) or cancel it by replacing with a 0 ETH self-send.
Using MetaMask's Speed Up / Cancel buttons
- Open MetaMask and find the pending transaction in Activity.
- Click "Speed Up" to broadcast a replacement with higher gas, or click "Cancel" to attempt a 0 ETH replacement.
- Confirm and wait for the replacement to be mined.
Notes: Speed Up/Cancel only appear if your provider and the tx state allow replacements. If you don't see those options, proceed to manual replacement below.
Manual replacement (custom nonce)
- Enable custom nonces: Settings > Advanced > Toggle "Customize transaction nonce".
- Find the stuck transaction's nonce (in MetaMask activity or on the explorer).
- Create a new transaction: send 0 ETH to your own address, set the nonce to the stuck nonce, and set gas (EIP-1559 fields: maxPriorityFee and maxFee) higher than the original.
- Confirm. This should replace the pending tx on-chain.
Practical tip: set the replacement gas at least 10%–25% above the original; if the network is congested I often use 30%–50% higher to ensure the miner/validator prefers the replacement.
What Reset Account does (and doesn't)
Reset Account (Settings > Advanced) clears MetaMask's local transaction history. It does not cancel transactions on-chain. Use Reset when MetaMask shows outdated status, not to remove a real pending transaction from the blockchain. See /reset-delete-and-reinstall for details.
Ledger + MetaMask: "can't confirm transaction" and stuck flows
Common Ledger causes:
- Ethereum app not open on the Ledger device.
- Firmware or Ethereum app outdated.
- Contract requires blind signing (some contracts need this enabled on older Ledger firmware).
- USB connection or browser permission issues.
Fixes I use: update firmware and the Ethereum app, re-open the Ethereum application on the Ledger, and replug the device. If a contract call still won't confirm, check the Ledger troubleshooting guide at /ledger-with-metamask-guide and the dedicated errors page /ledger-errors-and-troubleshooting.
And yes — sometimes the solution was simply using a different USB cable. Small things.
Connection errors: "a wallet connection request is already pending" and WalletConnect quirks
This happens when a dApp initiated a connection but the browser popup was blocked or the previous connection request is unresolved. Steps:
- Close browser popups and refresh the dApp.
- In MetaMask, review Connected Sites and remove the site if it looks stuck (/disconnect-connected-sites).
- For WalletConnect, disconnect from the mobile wallet and reconnect (/connect-to-dapps-walletconnect).
Why does this often happen? Browser popup blockers and slow WalletConnect QR handshakes. Patience helps.
Nonce mismatch, RPC issues, and when explorers disagree
Nonce mismatches occur when the network's expected nonce for your account doesn't match what MetaMask is sending. Causes include pending transactions on a different node, multiple clients sending txs from the same private key, or an unreliable RPC node.
Diagnosis:
- Check your account nonce on a block explorer (/using-etherscan-with-metamask).
- Switch RPC providers (Settings > Networks > Add / Custom RPC) or use a known provider (/custom-rpc-network-settings).
Fixes: replace the missing nonce with a 0 ETH self-send (same nonce), or use Reset Account after confirming no real pending tx exists. If you run your own node, sync status matters — see /developer-rpc-and-node-guide.
Prevention: habits and settings that reduce failures
- Always keep a small ETH buffer for gas on each network. (I keep ~0.01–0.05 ETH on mainnet for quick replacements.)
- Enable "Customize transaction nonce" only when needed — misuse can cause more nonce issues.
- For hardware wallets, keep firmware and app versions current.
- Use MetaMask's "Advanced gas controls" to check EIP-1559 fields; prefer setting both maxPriorityFee and maxFee.
- Revoke unlimited approvals regularly (/token-allowances-and-revoke) to reduce contract exposure.
But no method is perfect. Smart contract calls can still revert because of logic inside the contract.
FAQ
Q: Is it safe to keep crypto in a hot wallet?
A: Hot wallets are convenient for DeFi but carry higher risk than cold storage. I keep active funds in a hot wallet and long-term holdings in hardware wallets. See the backup guide: /seed-phrase-backup-recovery and the security checklist: /security-checklist.
Q: How do I revoke token approvals if a contract misbehaves?
A: Use a revoke tool or the "Revoke" flow in the dApp (and confirm on explorer) — see /token-allowances-and-revoke for step-by-step guidance.
Q: What happens if I lose my phone?
A: If you have your seed phrase, you can restore on another device. If not, funds are unrecoverable. Secure your seed phrase and follow the recovery steps at /seed-phrase-backup-recovery.
Conclusion & next steps
MetaMask transaction errors fall into a few repeatable patterns: contract reverts, gas/nonce issues, connection/WalletConnect quirks, and hardware-wallet confirmation problems. Diagnose with an explorer, try Speed Up/Cancel, and use a custom-nonce replacement when needed.
If you use Ledger, consult /ledger-with-metamask-guide and /ledger-errors-and-troubleshooting. If pending transactions are frequent, read /pending-transaction-troubleshooting and review gas mechanics at /gas-fees-eip1559-l2.
If you want step-by-step walkthroughs for the precise buttons and menus, check the related how-to pages: install and setup (/install-metamask-chrome-extension), mobile setup (/metamask-mobile-ios-android), and send/receive flows (/send-receive-with-metamask).
Want help with an actual stuck transaction? I often resolve them by replacing the nonce with a 0 ETH self-send; give that a try. And if that doesn't work, consult the hardware or RPC guides linked above.
