Documentation

Errors

All errors in ethers include properties to ensure they are both human-readable (i.e. .message) and machine-readable (i.e. .code).

The isError function can be used to check the error code and provide a type guard for the properties present on that error interface.

TYPES

<src>CallExceptionAction⇒ "call" | "estimateGas" | "getTransactionResult" | "sendTransaction" | "unknown"

The action that resulted in the call exception.

<src>CallExceptionTransaction⇒ { data: string , from?: string , to: null | string }

The related transaction that caused the error.

<src>CodedEthersError⇒ TODO(A1Bconditional(@TODO-000))

A conditional type that transforms the ErrorCode T into its EthersError type.

All errors emitted by ethers have an ErrorCode to help identify and coalesce errors to simplify programmatic analysis.

Each ErrorCode is the code proerty of a coresponding EthersError.

Generic Errors

"UNKNOWN_ERROR" - see UnknownError

"NOT_IMPLEMENTED" - see NotImplementedError

"UNSUPPORTED_OPERATION" - see UnsupportedOperationError

"NETWORK_ERROR" - see NetworkError

"SERVER_ERROR" - see ServerError

"TIMEOUT" - see TimeoutError

"BAD_DATA" - see BadDataError

"CANCELLED" - see CancelledError

Operational Errors

"BUFFER_OVERRUN" - see BufferOverrunError

"NUMERIC_FAULT" - see NumericFaultError

Argument Errors

"INVALID_ARGUMENT" - see InvalidArgumentError

"MISSING_ARGUMENT" - see MissingArgumentError

"UNEXPECTED_ARGUMENT" - see UnexpectedArgumentError

"VALUE_MISMATCH" - unused

Blockchain Errors

"CALL_EXCEPTION" - see CallExceptionError

"INSUFFICIENT_FUNDS" - see InsufficientFundsError

"NONCE_EXPIRED" - see NonceExpiredError

"REPLACEMENT_UNDERPRICED" - see ReplacementUnderpricedError

"TRANSACTION_REPLACED" - see TransactionReplacedError

"UNCONFIGURED_NAME" - see UnconfiguredNameError

"OFFCHAIN_FAULT" - see OffchainFaultError

User Interaction Errors

"ACTION_REJECTED" - see ActionRejectedError

<src>ErrorInfo⇒ Omit< T, "code" | "name" | "message" | "shortMessage" > & { shortMessage?: string }

An error may contain additional properties, but those must not conflict with any implicit properties.

FUNCTIONS

<src>assert(check: unknown, message: string, code: K, info?: ErrorInfo < T >)⇒ boolean

Throws an EthersError with message, code and additional error info when check is falsish..

<src>assertArgument(check: unknown, message: string, name: string, value: unknown)⇒ boolean

A simple helper to simply ensuring provided arguments match expected constraints, throwing if not.

In TypeScript environments, the check has been asserted true, so any further code does not need additional compile-time checks.

<src>assertArgumentCount(count: number, expectedCount: number, message?: string)⇒ void

<src>assertNormalize(form: string)⇒ void

Throws if the normalization form is not supported.

<src>assertPrivate(givenGuard: any, guard: any, className?: string)⇒ void

Many classes use file-scoped values to guard the constructor, making it effectively private. This facilitates that pattern by ensuring the givenGaurd matches the file-scoped guard, throwing if not, indicating the className if provided.

<src>isCallException(error: any)⇒ boolean

Returns true if error is a [[CallExceptionError].

<src>isError(error: any, code: K)⇒ boolean

Returns true if the error matches an error thrown by ethers that matches the error code.

In TypeScript environments, this can be used to check that error matches an EthersError type, which means the expected properties will be set.

try {
  // code....
} catch (e) {
  if (isError(e, "CALL_EXCEPTION")) {
      // The Type Guard has validated this object
      console.log(e.data);
  }
}

<src>makeError(message: string, code: K, info?: ErrorInfo < T >)⇒ T

Returns a new Error configured to the format ethers emits errors, with the message, [[api:ErrorCode]] code and additional properties for the corresponding EthersError.

Each error in ethers includes the version of ethers, a machine-readable ErrorCode, and depending on code, additional required properties. The error message will also include the message, ethers version, code and all additional properties, serialized.

interface ActionRejectedError

inherits from EthersError

This Error indicates a request was rejected by the user.

In most clients (such as MetaMask), when an operation requires user authorization (such as signer.sendTransaction), the client presents a dialog box to the user. If the user denies the request this error is thrown.

PROPERTIES

The requested action.

<src>actionRejectedError.reason⇒ "expired" | "rejected" | "pending"

The reason the action was rejected.

If there is already a pending request, some clients may indicate there is already a "pending" action. This prevents an app from spamming the user.

interface BadDataError

inherits from EthersError

This Error indicates that a provided set of data cannot be correctly interpreted.

PROPERTIES

<src>badDataError.value⇒ any

The data.

interface BufferOverrunError

inherits from EthersError

This Error indicates an attempt was made to read outside the bounds of protected data.

Most operations in Ethers are protected by bounds checks, to mitigate exploits when parsing data.

PROPERTIES

<src>bufferOverrunError.buffer⇒ Uint8Array

The buffer that was overrun.

<src>bufferOverrunError.length⇒ number

The length of the buffer.

<src>bufferOverrunError.offset⇒ number

The offset that was requested.

interface CallExceptionError

inherits from EthersError

This Error indicates a transaction reverted.

PROPERTIES

<src>callExceptionError.action⇒ CallExceptionAction

The action being performed when the revert was encountered.

<src>callExceptionError.data⇒ null | string

The revert data returned.

<src>callExceptionError.invocation⇒ null | { args: Array< any > , method: string , signature: string }

The contract invocation details, if available.

<src>callExceptionError.reason⇒ null | string

A human-readable representation of data, if possible.

<src>callExceptionError.receipt⇒ TransactionReceipt

If the error occurred in a transaction that was mined (with a status of 0), this is the receipt.

<src>callExceptionError.revert⇒ null | { args: Array< any > , name: string , signature: string }

The built-in or custom revert error, if available

<src>callExceptionError.transaction⇒ CallExceptionTransaction

The transaction that triggered the exception.

interface CancelledError

inherits from EthersError

This Error indicates that the operation was cancelled by a programmatic call, for example to cancel().

interface EthersError

All errors in Ethers include properties to assist in machine-readable errors.

PROPERTIES

<src>ethersError.code⇒ ErrorCode

The string error code.

<src>ethersError.error⇒ Error

Any related error.

<src>ethersError.info⇒ Record< string, any >

Additional info regarding the error that may be useful.

This is generally helpful mostly for human-based debugging.

<src>ethersError.shortMessage⇒ string

A short message describing the error, with minimal additional details.

interface InsufficientFundsError

inherits from EthersError

The sending account has insufficient funds to cover the entire transaction cost.

PROPERTIES

<src>insufficientFundsError.transaction⇒ TransactionRequest

The transaction.

interface InvalidArgumentError

inherits from EthersError

This Error indicates an incorrect type or value was passed to a function or method.

PROPERTIES

<src>invalidArgumentError.argument⇒ string

The name of the argument.

<src>invalidArgumentError.info⇒ Record< string, any >

<src>invalidArgumentError.value⇒ any

The value that was provided.

interface MissingArgumentError

inherits from EthersError

This Error indicates there were too few arguments were provided.

PROPERTIES

<src>missingArgumentError.count⇒ number

The number of arguments received.

<src>missingArgumentError.expectedCount⇒ number

The number of arguments expected.

interface NetworkError

inherits from EthersError

This Error indicates a problem connecting to a network.

PROPERTIES

<src>networkError.event⇒ string

The network event.

interface NonceExpiredError

inherits from EthersError

The sending account has already used this nonce in a transaction that has been included.

PROPERTIES

<src>nonceExpiredError.transaction⇒ TransactionRequest

The transaction.

interface NotImplementedError

inherits from EthersError

This Error is mostly used as a stub for functionality that is intended for the future, but is currently not implemented.

PROPERTIES

<src>notImplementedError.operation⇒ string

The attempted operation.

interface NumericFaultError

inherits from EthersError

This Error indicates an operation which would result in incorrect arithmetic output has occurred.

For example, trying to divide by zero or using a uint8 to store a negative value.

PROPERTIES

<src>numericFaultError.fault⇒ string

The fault reported.

<src>numericFaultError.operation⇒ string

The attempted operation.

<src>numericFaultError.value⇒ any

The value the operation was attempted against.

interface OffchainFaultError

inherits from EthersError

A CCIP-read exception, which cannot be recovered from or be further processed.

PROPERTIES

<src>offchainFaultError.reason⇒ string

The reason the CCIP-read failed.

<src>offchainFaultError.transaction⇒ TransactionRequest

The transaction.

interface ReplacementUnderpricedError

inherits from EthersError

An attempt was made to replace a transaction, but with an insufficient additional fee to afford evicting the old transaction from the memory pool.

PROPERTIES

<src>replacementUnderpricedError.transaction⇒ TransactionRequest

The transaction.

interface ServerError

inherits from EthersError

This Error indicates there was a problem fetching a resource from a server.

PROPERTIES

<src>serverError.request⇒ FetchRequest | string

The requested resource.

<src>serverError.response⇒ FetchResponse

The response received from the server, if available.

interface TimeoutError

inherits from EthersError

This Error indicates that the timeout duration has expired and that the operation has been implicitly cancelled.

The side-effect of the operation may still occur, as this generally means a request has been sent and there has simply been no response to indicate whether it was processed or not.

PROPERTIES

<src>timeoutError.operation⇒ string

The attempted operation.

<src>timeoutError.reason⇒ string

The reason.

<src>timeoutError.request⇒ FetchRequest

The resource request, if available.

interface TransactionReplacedError

inherits from EthersError

A pending transaction was replaced by another.

PROPERTIES

<src>transactionReplacedError.cancelled⇒ boolean

If the transaction was cancelled, such that the original effects of the transaction cannot be assured.

<src>transactionReplacedError.hash⇒ string

The hash of the replaced transaction.

<src>transactionReplacedError.reason⇒ "repriced" | "cancelled" | "replaced"

The reason the transaction was replaced.

<src>transactionReplacedError.receipt⇒ TransactionReceipt

The receipt of the transaction that replace the transaction.

<src>transactionReplacedError.replacement⇒ TransactionResponse

The transaction that replaced the transaction.

interface UnconfiguredNameError

inherits from EthersError

This Error indicates an ENS name was used, but the name has not been configured.

This could indicate an ENS name is unowned or that the current address being pointed to is the ZeroAddress.

PROPERTIES

<src>unconfiguredNameError.value⇒ string

The ENS name that was requested

interface UnexpectedArgumentError

inherits from EthersError

This Error indicates too many arguments were provided.

PROPERTIES

<src>unexpectedArgumentError.count⇒ number

The number of arguments received.

<src>unexpectedArgumentError.expectedCount⇒ number

The number of arguments expected.

interface UnknownError

inherits from EthersError

This Error is a catch-all for when there is no way for Ethers to know what the underlying problem is.

interface UnsupportedOperationError

inherits from EthersError

This Error indicates that the attempted operation is not supported.

This could range from a specific JSON-RPC end-point not supporting a feature to a specific configuration of an object prohibiting the operation.

For example, a Wallet with no connected Provider is unable to send a transaction.

PROPERTIES

<src>unsupportedOperationError.operation⇒ string

The attempted operation.