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.

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.

Common Causes

Debugging

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.

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.

Examples
// Bad: ethers.Wallet(privateKey) // [Signer: missing new [ See: https://links.ethers.org/v5-errors-MISSING_NEW ]] { // code: 'MISSING_NEW', // reason: 'missing new' // } // Good: new ethers.Wallet(privateKey) // Wallet { // _isSigner: true, // _mnemonic: [Function (anonymous)], // _signingKey: [Function (anonymous)], // address: '0x14791697260E4c9A71f18484C9f997B308e59325', // provider: null // }

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.

NUMERIC_FAULT

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.

Overflow

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.

Examples
// One ether is outside the safe range BigNumber.from(1000000000000000000) // [Error: overflow [ See: https://links.ethers.org/v5-errors-NUMERIC_FAULT-overflow ]] { // code: 'NUMERIC_FAULT', // fault: 'overflow', // operation: 'BigNumber.from', // reason: 'overflow', // value: 1000000000000000000 // } // Providing the value as a string is safe BigNumber.from("1000000000000000000") // { BigNumber: "1000000000000000000" } // As is using a bigint (notice the `n` suffix) BigNumber.from(1000000000000000000n) // { BigNumber: "1000000000000000000" } // But most often, the `parseEther` function solves this utils.parseEther("1.0") // { BigNumber: "1000000000000000000" }

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

Examples
// BigNumbers cannot be created with a fractional component BigNumber.from(1.2) // [Error: underflow [ See: https://links.ethers.org/v5-errors-NUMERIC_FAULT-underflow ]] { // code: 'NUMERIC_FAULT', // fault: 'underflow', // operation: 'BigNumber.from', // reason: 'underflow', // value: 1.2 // } // Parsing a value with more decimals than the type utils.parseUnits("1.34", 1); // [Error: fractional component exceeds decimals [ See: https://links.ethers.org/v5-errors-NUMERIC_FAULT ]] { // code: 'NUMERIC_FAULT', // fault: 'underflow', // operation: 'parseFixed', // reason: 'fractional component exceeds decimals' // }

Division by zero

This error occurs when dividing by zero or attempting to take the modulo zero.

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.

Unsupported Operation

The ethers BigNumber does not support negative powers or bitwise shift operation using negative values.

Examples
two = BigNumber.from(2); two.pow(-2) // [Error: negative-power [ See: https://links.ethers.org/v5-errors-NUMERIC_FAULT-unsupported ]] { // code: 'NUMERIC_FAULT', // fault: 'negative-power', // operation: 'pow', // reason: 'negative-power' // } // Cannot use negative values to alter shift direction two.shr(-1) // [Error: negative-width [ See: https://links.ethers.org/v5-errors-NUMERIC_FAULT-unsupported ]] { // code: 'NUMERIC_FAULT', // fault: 'negative-width', // operation: 'shr', // reason: 'negative-width' // }

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.

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.

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.