All errors in ethers are created by the Logger class, which includes a number of additional properties and extra data, which can assist in debugging and when submitting issues.
When submitting an issue, please include as much of any error as possible, but also make sure you understand the error and have tried suggested solutions both in this trouble-shooting document and any other issues you find when searching the GitHub issues.
This error occurs when a call or transaction is used to interact with the blockchain reverts (via revert, require, et cetera).
Due to the overall flexibility of Ethereum and Turing Completeness, there is a large variety of reasons this can occur and troubleshooting requires attention.
- The code does not exist on-chain. This may happen if you failed to wait until the contract was deployed, the address is incorrect or if you are connected to a different network than the contract has been deployed. Check the code exists using
provider.getCode(address). - The wrong code is being accessed, for example if an artifact file was not correctly updated so an older instance of the contract is being called
- The contract is failing during a
requirestatement. For example, if a contract method requires an admin account to be used, but the contract is connected to another Signer. - The wrong ABI is being used to interact with a contract.
- Always double check the address and network you are connected to and use
provider.getCode(address)to verify the deployed code matches your most recent version. - Try accessing other, simpler contract methods to verify the account is correct.
This usually occurs when a transaction is attempted, but the sending account does not have enough ether to cover the cost of the transaction.
A transaction has an intrinsic cost which must be met, which accounts for the value being sent, the base fee of the transaction, additional fees per byte of calldata and whether the transaction will create a new account (i.e. the to is empty).
This error can also happen if provider.estimateGas is used with a non-zero fee (i.e. gasPrice, maxFeePerGas or maxPriorityFeePerGas). If any fee properties are specified, the from account must have sufficient ether to execute the transaction.
Classes in ethers must be instantiated with the new operator. This error indicates that a Class is attempting to be used as a function.
This error occurs when a transaction is being sent with a nonce that is lower than next required nonce.
Each Ethereum transaction requires a nonce property equal to the index of that transaction for that account for all time. So, if an account has send four transactions over its lifetime, that means the nonces 0 though 3 (inclusive) have been used. The next transaction must use a nonce of 4. Attempting to re-use a nonce less than 4 will result in this error.
A numeric fault is a consequence of performing an illegal operation with numeric values, such as dividing by zero.
The error will indicate the operation, which further indicates the reason for the error.
JavaScript uses IEEE 754 double-precision binary floating point numbers to represent numeric values. As a result, there are holes in the integer set after 9,007,199,254,740,991; which is problematic for Ethereum because that is only around 0.009 ether (in wei), which means any value over that will begin to experience rounding errors.
As a result, any attempt to use a number which is outside the safe range, which would result in incorrect values, an error is thrown.
In general, numbers should be kept as strings, BigNumber instances or using ES2020 bigints, which all can safely be used without loss of precission.
Numeric underflow should not be confused with overflow.
Numeric underflow occurs when the precission of a value cannot be safely represented in the current data type.
Common Causes
- Using values with fractional componets (e.g.
BigNumber.from(1.2)). If you require fractions, you must use the FixedNumber class. - Parsing string values that have more decimals than the unit supports (e.g.
parseUnits("1.33", 1)).
This error occurs when dividing by zero or attempting to take the modulo zero.
The ethers BigNumber does not support bitwise operators on negative numbers which can result in the need for an infinite number of set bits.
Other implementations may use negative values to indicate this, but this is considered out of scope for ethers.
The ethers BigNumber does not support negative powers or bitwise shift operation using negative values.
To prevent nodes from being overloaded with junk transactions, a transaction is only accepted into the memory pool if it has a reasonable chance of being actually mined, which means that the account has sufficient balance, the nonce is correct and the fee seems reasonable.
Once a transaction is in the memory pool though, to prevent an account from flooding the network with many different transactions with the same nonce (each of which satisfies the above criteria), to replace an existing transaction an additional committment of a fee must be made by increasing the promised fee.
When replacing a legacy non-EIP1559 transaction, the gasPrice must be increased. When replacing a modern, EIP-1559 transaction, the maxPriorityFeePerGas should be increased.
This error is thrown when waiting for a transaction which has been replaced by another, by the sender submitting a second transaction with the same nonce, while the transaction was pending in the transaction pool.
You can learn more about this feature in the .wait method of TransactionResponse.
During gas estimation it is possible that a transaction would actually fail (and hence has no reasonable estimate of gas requirements) or that the transaction is complex in a way that does not permit a node to estimate the gas requirements, in which case this error is thrown.
In almost all cases, this will unfortunately require you specify an explicit gasLimit for your transaction, which will disable ether's automatic population of the gasLimit field, which will cause this error to go away.
To dial in an appropriate gas limit, try a value that is much higher than you expect, and then make a few transactions to discover reasonable values and then you can reduce this value down to that ballpark.
Keep in mind this error can also occur if the transaction would legitimately fail, in which case the root cause must be addressed, such as ensuring the correct Signer is being used, the appropriate allowance for an ERC-20 token has been approved, etc.