User Guide: Transactions

This article consists of an explanation and links to resources surrounding transactions and why they fail, and further down, links to common failed transaction scenarios and how to address them.

 

Anatomy of a blockchain transaction

When we talk about 'transactions' on a public blockchain network, we're usually talking about interactions between two addresses; in other words, tokens, be they fungible or non, or other crypto-assets being 'sent' from one address to another. There are also transactions referred to as "internal transactions", which are interactions that occur between smart contracts, and for the most part fall outside of the scope of this article.

For more on blockchain networks and how they work in general, check out our intro article here, and if you get stuck on any unfamiliar words, our glossary is always available.

For clarity's sake, nothing is actually being sent anywhere. Remember, a smart contract-enabled blockchain network like Ethereum has a number of different components, or functions, including what we would call a "computer", the Ethereum Virtual Machine, or EVM, which is capable of running programs (so-called 'smart contracts'). The 'backbone' of the system, however, is a distributed ledger: imagine a spreadsheet that contains, on one side, every single Ethereum wallet address, and each address has a column for each type of crypto-asset that it holds. 

Let's use an example for illustration. Say that Guillaume wants to send a transaction to Dolores. Guillaume has 1.36 ETH in his account, and he plans on sending Dolores 0.5 ETH. Sounds like a good day for Dolores. 

Guillaume opens up his MetaMask wallet, enters Dolores' address, configures the gas parameters that he's comfortable with paying, and hits 'send'.

At this point, the transaction enters a local temporary holding status, known as the local memory pool, or local mempool. The transaction will then get 'picked up' by the closest node in the network; depending on Guillaume's gas settings, his transaction will be prioritized (the more Guillaume is willing to pay per unit of gas, the faster his transaction will be processed), and propagated to other nodes in the network. The nodes will do the work of verifying that Guillaume has the ETH to spend, and then will actually perform the 'transaction': the ledger will be modified; 0.5 will be debited from Guillaume's balance, and 0.5 will be credited to Dolores'. 

'The moving hand, having writ, moves on': ETH didn't move through a network per se; it wasn't an email sent from Guillaume's computer to Dolores' MetaMask inbox or anything of the sort. Guillaume sent a request, authenticated by his private keys through MetaMask, to the network to debit his account and credit Dolores', and after the verification process programmed into the network's protocols, this was done. 

That's all there is to a transaction: a request to the ledger to reallocate something from one address to another.

 

When things go wrong

Things can go wrong for a number of reasons. Often, they're 'software in nature': MetaMask has a bug, or something was misconfigured regarding the network you're trying to use; there was a connectivity error.

A common issue is that the user, in an attempt to pay less for their transaction, sets a very low gas limit, and network conditions are so congested that there isn't space in any blocks for such a "cheap" transaction, sometimes for a very long time: eventually, this transaction will become "stale" and will have to be cancelled by the user. 

If you've sent a transaction and it hasn't been finalized, its status will be shown as "pending" in MetaMask. 

If you sent a transaction, and it failed, the most likely cause is a lack of gas: you "ran out of gas", in other words, the transaction had a cost in gas that, when multiplied by the gas price, resulted in a total amount of the network's native currency that was greater than what you had in your wallet. 

For more on calculating gas, consult our gas guide here.

This can happen for a number of reasons, but one thing to consider is what the transaction is that you're trying to carry out. Minting an NFT during peak network traffic times can be very gas-intensive; if you're trying out a new or experimental transaction, it may be worth trying on a test network before paying real live network fees.

 

Fixing the problem

Key Factor #1: Local or Broadcast to Network

As you go about diagnosing your transaction issue, especially when it comes to a pending transaction, you need to look at whether the transaction is still in your local mempool, or whether it has made it to the network and is stuck there for whatever reason. If it is just in your local mempool, the solution could be as simple as locking, and unlocking, your MetaMask wallet (make sure you know your password and have your Secret Recovery Phrase backed up before you do). If it's made it to the network, the solution could be more complicated.

For more on fixing these problems, see the links below.

Key Factor #2: Nonce

As discussed elsewhere, this word can mean a few different things. ln this context, it means, roughly, 'transaction number', starting from the first transaction made by the sending address. You can get yourself into real trouble if you, for example, are firing two different transactions from different instances of MetaMask with the same wallet address at the same time. Your address' transactions need to be in increasing order according to their nonce. However, just as nonces are capable of causing a stuck transaction, they can be the key to getting a transaction unstuck.

For more on that technique, see here.

 

Next Steps

If you have a failed or pending transaction, consult the following resources for assistance.

How to send tokens from your MetaMask wallet

How to speed up or cancel a pending transaction

Failed (reverted) swap

Why did my transaction fail with an "Out of Gas" error?

Uniswap Troubleshooting

User Guide: Gas

Can I reverse an already confirmed transaction?

 

FAQs

Q: One account in my wallet has a pending or in-queue transaction. Can I start another transaction from a different account within the same wallet?
A: Yes, you can. The nonce is counted per account, not per wallet.

Was this article helpful?
23 out of 229 found this helpful

Articles in this section

See more
MetaMask Support on Twitter
Beware of scam Twitter accounts. Never give anyone your Secret Recovery Phrase!
MetaMask YouTube
Fow how-to and support videos please visit our channel