250 lines
8.6 KiB
Plaintext
250 lines
8.6 KiB
Plaintext
_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 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<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
|
|
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.
|