ethers.js/docs.wrm/troubleshooting/errors.wrm

_section: Error Codes @<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 @<help-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 @<help-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 @<help-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<javascript>

//_hide: privateKey = "0x0123456789012345678901234567890123456789012345678901234567890123";
//_hide: Wallet = ethers.Wallet;

// Bad:
//_throws:
ethers.Wallet(privateKey)
//_log:

// Good:
//_result:
new ethers.Wallet(privateKey)
//_log:


_subsection: NONCE_EXPIRED @<help-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 @<help-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 @<help-NUMERIC_FAULT-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<javascript>

// 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 @<help-NUMERIC_FAULT-underflow>

Numeric underflow sbould 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. ``parseUints("1.33", 1)``).

_code: Examples @lang<javascript>

// 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 @<help-NUMERIC_FAULT-division-by-zero>

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


_heading: Unbound Result @<help-NUMERIC_FAULT-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 @<help-NUMERIC_FAULT-unsupported>

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

_code: Examples @lang<javascript>

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 @<help-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 @<help-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 @<help-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
estiamte 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.