_section: Error Codes @ 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. _subsection: CALL_EXCEPTION @ 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. _heading: Common Causes - 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 ``require`` statement. 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. _heading: Debugging - 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. _subsection: INSUFFICIENT_FUNDS @ 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. _subsection: MISSING_NEW @ Classes in ethers must be instantiated with the ``new`` operator. This error indicates that a Class is attempting to be used as a function. _code: Examples @lang //_hide: privateKey = "0x0123456789012345678901234567890123456789012345678901234567890123"; //_hide: Wallet = ethers.Wallet; // Bad: //_throws: ethers.Wallet(privateKey) //_log: // Good: //_result: new ethers.Wallet(privateKey) //_log: _subsection: NONCE_EXPIRED @ 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. _subsection: NUMERIC_FAULT @ A [numeric fault](errors--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. _heading: Overflow @ JavaScript uses [IEEE 754 double-precision binary floating point](link-wiki-ieee754) 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. _code: Examples @lang // One ether is outside the safe range //_throws: BigNumber.from(1000000000000000000) //_log: // Providing the value as a string is safe //_result: BigNumber.from("1000000000000000000") //_log: // As is using a bigint (notice the `n` suffix) //_result: BigNumber.from(1000000000000000000n) //_log: // But most often, the `parseEther` function solves this //_result: utils.parseEther("1.0") //_log: _heading: Numeric Underflow @ 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)``). _code: Examples @lang // BigNumbers cannot be created with a fractional component //_throws: BigNumber.from(1.2) //_log: // Parsing a value with more decimals than the type //_throws: utils.parseUnits("1.34", 1); //_log: _heading: Division by zero @ This error occurs when dividing by zero or attempting to take the modulo zero. _heading: Unbound Result @ 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. _heading: Unsupported Operation @ The ethers [[BigNumber]] does not support negative powers or bitwise shift operation using negative values. _code: Examples @lang two = BigNumber.from(2); //_throws: two.pow(-2) //_log: // Cannot use negative values to alter shift direction //_throws: two.shr(-1) //_log: _subsection: REPLACEMENT_UNDERPRICED @ 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. _subsection: TRANSACTION_REPLACED @ 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](providers-TransactionResponse). _subsection: UNPREDICTABLE_GAS_LIMIT @ 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.