Parse Ethers.js errors with ease ๐Ÿ’…๐Ÿป

Overview

ethers-error-parser

Tests npm version codecov

Parse Ethers.js errors with ease ๐Ÿ’…๐Ÿป

Highlights

  • Zero dependencies ๐Ÿงน
  • Lightweight (637 bytes gzipped) ๐Ÿ“ฆ
  • Simple to use โšก๏ธ
  • Work in progress ๐Ÿšง

Why

Ethers.js is well known for its cryptic error messages. Whenever a transaction fails you will get an error message that combines plain text and JSON stringified string like this:

Error: cannot estimate gas; transaction may fail or may require manual gas limit (error={"code":-32603,"message":"execution reverted: Code has already claimed","data":{"originalError":{"code":3,"data":"0x08c379a000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000018436f64652068617320616c726561647920636c61696d65640000000000000000","message":"execution reverted: Code has already claimed"}}}, method="estimateGas", transaction={"from":"0xC16f5C62b29704F7aBECb27A3cb7E12a91383261","to":"0xb21FFFd62BD2f4aBd2a1dC34A2302Fda364977a0","data":"0xd2c34d3f0000000000000000000000000000000000000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000063132333435360000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004153801a64156372ec7cd1d91868dd35ed68972dfa8b347c59db14bc49b753ed576fbe8a2bc00b6d0ba5dc8429c01748ae55e87dffa9547aafeb844aa40bb6c3e31b00000000000000000000000000000000000000000000000000000000000000","accessList":null}, code=UNPREDICTABLE_GAS_LIMIT, version=providers/5.5.1)

Your users deserve to get amazing feedback on failing transactions. Thanks to ethers-error-parser you can do that with ease.

Work in progress

This package is a work in progress. Although it is not yet complete and many Ethers errors could be handled more elegantly, it is safe to use in production as it is. Some insights is better than no insights.

This package is being used in different production projects and it is in constant evolution based on the needs of these projects. If you find some error that is not handled yet or that does not provide a great context, please open an issue or pull request ๐Ÿ™

Getting started

  1. Install the package
yarn add @enzoferey/ethers-error-parser
  1. Use it
import { getParsedEthersError } from "@enzoferey/ethers-error-parser";

try {
  const transaction = await someContract.someMethod();
  await transaction.wait();
} catch (error) {
  const parsedEthersError = getParsedEthersError(error);
  // parsedError.errorCode - contains a well defined error code (see full list below)
  // parsedError.context - contains a context based string providing additional information
  // profit ! ๐Ÿ’…๐Ÿป
}

Return value

When using getParsedEthersError you will get back an object containing a well known errorCode property and an optional context property with additional information. The TypeScript type definition looks like the following:

interface ReturnValue {
  errorCode: string;
  context?: string;
}

Here is the complete list of returned objects:

errorCode context
TRANSACTION_RUN_OUT_OF_GAS The transaction gas limit as a string.
TRANSACTION_UNDERPRICED undefined
REJECTED_TRANSACTION The reason why the transaction rejected.
EXECUTION_REVERTED The reason why the transaction reverted.
UNKNOWN_ERROR Some code or description of the error if available. undefined otherwise.

If you find some error that is not handled yet or that does not provide a great context, please open an issue or pull request ๐Ÿ™

Comments
  • feat: expose types for better TypeScript usage

    feat: expose types for better TypeScript usage

    Is your pull request closing an issue?

    Closes #39

    Please explain the main changes of your pull request

    Export types

    Checklist

    • [x] Have you added any new returned codes to the README file ?
    enhancement 
    opened by challet 4
  • [FEATURE] Parsing the message key inside error.data object

    [FEATURE] Parsing the message key inside error.data object

    Should be able to parse the exact reason from the message key which is inside the error.data object.

    This message is the reason for transaction failure often written inside the require function of smart contracts.

    enhancement 
    opened by spandansingh 4
  • [BUG] Missing EthersError type with Typescript

    [BUG] Missing EthersError type with Typescript

    Describe the bug

    Using the getParsedEthersError in a typescript file leads to this error

    TS2345: Argument of type 'unknown' is not assignable to parameter of type 'EthersError'.
        37 |       contract = yield call(async() => await factory.deploy(payload))
        38 |     } catch(e) {
      > 39 |       getParsedEthersError(e)
           |                            ^
        40 |     }
    

    And trying to import it is not working :

    Module '"@enzoferey/ethers-error-parser"' has no exported member 'EthersError'.

    Expected behavior

    The library exposes the types that may be used externally, so this can be written :

    import { getParsedEthersError, EthersError } from "@enzoferey/ethers-error-parser"
    [โ€ฆ]
    getParsedEthersError(e as EthersError)
    
    bug 
    opened by challet 2
  • [BUG]

    [BUG]

    can no parse this: Error: Transaction has been reverted by the EVM: { "transactionHash": "0xce0f4a5f9e31a7fecac27452376cb27dc4fe5a0b1f2c02e83bf475c5d8ee7d8d", "transactionIndex": 0, "blockHash": "0xa384bb0a3a57972b3482ff372a4437905050612a3a3baadbc80ac1149803cf88", "blockNumber": 27552133, "cumulativeGasUsed": 37047, "gasUsed": 37047, "effectiveGasPrice": 2500000007, "from": "0x57c1b087a970d13e307fab65345439dea4ccba91", "to": "0x2dd39f44758f66fa125f83b0e89136b49a64e18a", "contractAddress": null, "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", "status": false, "error": "Reverted 0x41697264726f707065723a207465726d206c696d6974", "type": "0x2", "events": {} }

    bug 
    opened by hehaozhen11 2
  • [FEATURE] Export RETURN_VALUE_ERROR_CODES

    [FEATURE] Export RETURN_VALUE_ERROR_CODES

    Please add RETURN_VALUE_ERROR_CODES to the package exports.

    I would like to make a switch statement around error codes to handle errors nicely, but it isn't possible because my app code cannot access RETURN_VALUE_ERROR_CODES: screenshot

    enhancement 
    opened by skibitsky 2
  • [FEATURE] Handle Nonce Errors

    [FEATURE] Handle Nonce Errors

    Would it be possible to handle/parse nonce errors?

    As an example:

    Error: nonce has already been used [ See: https://links.ethers.org/v5-errors-NONCE_EXPIRED ] (error={"code":-32603,"message":"[ethjs-query] while formatting outputs from RPC '{\"value\":{\"code\":-32603,\"data\":{\"code\":-32000,\"message\":\"Nonce too low. Expected nonce to be 117 but got 1.\",\"data\":{\"message\":\"Nonce too low. Expected nonce to be 117 but got 1.\"}}}}'","stack":"{\n \"code\": -32603,\n \"message\": \"[ethjs-query] while formatting outputs from RPC '{\\\"value\\\":{\\\"code\\\":-32603,\\\"data\\\":{\\\"code\\\":-32000,\\\"message\\\":\\\"Nonce too low. Expected nonce to be 117 but got 1.\\\",\\\"data\\\":{\\\"message\\\":\\\"Nonce too low. Expected nonce to be 117 but got 1.\\\"}}}}'\",\n \"stack\": \"Error: [ethjs-query] while formatting outputs from RPC '{\\\"value\\\":{\\\"code\\\":-32603,\\\"data\\\":{\\\"code\\\":-32000,\\\"message\\\":\\\"Nonce too low. Expected nonce to be 117 but got 1.\\\",\\\"data\\\":{\\\"message\\\":\\\"Nonce too low. Expected nonce to be 117 but got 1.\\\"}}}}'\\n

    enhancement 
    opened by JohnSmithyy 2
  • feat: expose RETURN_VALUE_ERROR_CODES constant

    feat: expose RETURN_VALUE_ERROR_CODES constant

    Is your pull request closing an issue?

    Closes https://github.com/enzoferey/ethers-error-parser/issues/33.

    Please explain the main changes of your pull request

    Exports the RETURN_VALUE_ERROR_CODES constant so JavaScript users avoid typos and TypeScript users do not have to hardcode strings.

    opened by enzoferey 1
  • feat: support call reverted

    feat: support call reverted

    Is your pull request closing an issue?

    Closes https://github.com/enzoferey/ethers-error-parser/issues/26.

    Please explain the main changes of your pull request

    Supports calls reverts via the CALL_EXCEPTION ethers code.

    Checklist

    • [x] Have you added any new returned codes to the README file ?
    opened by enzoferey 1
  • feat: support transaction rejected via code

    feat: support transaction rejected via code

    Is your pull request closing an issue?

    Closes https://github.com/enzoferey/ethers-error-parser/issues/27.

    Please explain the main changes of your pull request

    Uses the code and action properties to determine if it was a rejected action and returns the message property as the context value.

    opened by enzoferey 1
  • docs: change to single pull request template

    docs: change to single pull request template

    I tried a multi template attempt at https://github.com/enzoferey/ethers-error-parser/pull/23 but it does not work like issue templates, so I'm switching to single "good old" pull request template.

    opened by enzoferey 1
  • feat: support unpredictable gas limit issues related to gas

    feat: support unpredictable gas limit issues related to gas

    Closes https://github.com/enzoferey/ethers-error-parser/issues/17 & https://github.com/enzoferey/ethers-error-parser/issues/18.

    Fixes parsing for https://github.com/enzoferey/ethers-error-parser/pull/16.

    opened by enzoferey 1
  • feat: support contract not deployed

    feat: support contract not deployed

    Is your pull request closing an issue?

    No

    Please explain the main changes of your pull request

    ether.js Contract.deployed function can throw an error about the contract not being deployed.

    This adds a new error type CONTRACT_NOT_DEPLOYED for this case with the address having been requested as a context.

    Checklist

    • [x] Have you added any new returned codes to the README file ?
    opened by challet 3
  • [Question] Error format depending on the EVM backend ?

    [Question] Error format depending on the EVM backend ?

    Hello, while using Ganache as a development backend, some errors are not handled as expected. For instance with the following one (the context is a call to ethers estimateGas method which makes a dry run of the transaction and so can throw similar errors as the actual transaction):

    {
    	"code": -32603,
    	"data": {
    		"code": -32000,
    		"data": {
    			"hash": null,
    			"message": "revert",
    			"programCounter": 1420,
    			"reason": "[revert message]",
    			"result": "0x08c379a00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000c34303920436f6e666c6963740000000000000000000000000000000000000000"
    		},
    		"message": "VM Exception while processing transaction: revert [revert message]",
    		"name": "RuntimeError",
    		"stack": "RuntimeError: VM Exception while processing transaction: revert [revert message]\n    at exactimate ([path]/node_modules/ganache/dist/node/1.js:2:182333)"
    	},
    	"message": "Internal JSON-RPC error."
    }
    

    It is parsed as { errorCode: 'UNKNOWN_ERROR', context: '-32603' } while imho it should return the EXECUTION_REVERTED one : https://github.com/enzoferey/ethers-error-parser/blob/d4e452b411738e9b97a5e9e8978ce875a46bd967/lib/constants.ts#L6

    The text message looks really specific to Ganache and I'm wondering whether the whole error structure is also specific to it. How could it be then handled by the error parser ?

    opened by challet 6
  • [FEATURE] Support call where value + gas is not covered

    [FEATURE] Support call where value + gas is not covered

    Describe the feature

    {
      code: -32603,
      data: {
        code: -32000,
        message: "err: insufficient funds for gas * price + value: address 0x.... have XXX want XXX (supplied gas XXX)"
      }
    }
    
    enhancement 
    opened by enzoferey 0
Releases(v0.2.3)
  • v0.2.3(Dec 15, 2022)

    Highlights

    • Exports the EthersError and ReturnValue types for easier usage in TypeScript.

    Changes

    • feat: expose types for better TypeScript usage #40
    • core: bump version to v0.2.3 #41
    Source code(tar.gz)
    Source code(zip)
  • v0.2.2(Sep 25, 2022)

    Highlights

    • Exports the RETURN_VALUE_ERROR_CODES constants object that defines the possible errorCode returned by getParsedEthersError.

    Changes

    • feat: expose RETURN_VALUE_ERROR_CODES constant #34
    • core: bump version to v0.2.2 #35
    Source code(tar.gz)
    Source code(zip)
  • v0.2.1(Sep 18, 2022)

    Highlights

    • Supports transaction rejected via ethers code ACTION_REJECTED.
    • Supports calls reverts via ethers code code CALL_EXCEPTION.

    Changes

    • docs: add missing return error codes #22
    • docs: add pull requests templates #23
    • docs: change to single pull request template #24
    • docs: fix checklist title formatting #25
    • feat: support transaction rejected via code #28
    • feat: support call reverted #29
    • docs: display package size via badge #30
    • core: bump version to v0.2.1 #31
    Source code(tar.gz)
    Source code(zip)
  • v0.2.0(Aug 20, 2022)

    Breaking changes

    • TRANSACTION_RUN_OUT_OF_GAS returned error code has been renamed to TRANSACTION_RAN_OUT_OF_GAS.

    Changes

    • docs: fix yarn install typo https://github.com/enzoferey/ethers-error-parser/pull/4
    • docs: create issue templates https://github.com/enzoferey/ethers-error-parser/pull/10
    • refactor: fix run past tense typo https://github.com/enzoferey/ethers-error-parser/pull/11
    • core: improve types file test coverage ignore pattern https://github.com/enzoferey/ethers-error-parser/pull/12
    • feat: support nonce too low error https://github.com/enzoferey/ethers-error-parser/pull/14
    • feat: support execution reverted during gas estimation https://github.com/enzoferey/ethers-error-parser/pull/15
    • feat: support insufficient funds for gas https://github.com/enzoferey/ethers-error-parser/pull/16
    • feat: support unpredictable gas limit issues related to gas https://github.com/enzoferey/ethers-error-parser/pull/19
    • feat: update dependencies https://github.com/enzoferey/ethers-error-parser/pull/20
    • core: bump version to v0.2.0 https://github.com/enzoferey/ethers-error-parser/pull/21
    Source code(tar.gz)
    Source code(zip)
  • v0.1.1(Jul 25, 2022)

    Changes

    • docs: improve coverage display https://github.com/enzoferey/ethers-error-parser/pull/2
    • core: implement first release improvements https://github.com/enzoferey/ethers-error-parser/pull/3
    Source code(tar.gz)
    Source code(zip)
  • v0.1.0(Jul 23, 2022)

    Parse Ethers.js errors with ease ๐Ÿ’…๐Ÿป

    This package is a work in progress. Although it is not yet complete and many Ethers errors could be handled more elegantly, it is safe to use in production as it is. Some insights is better than no insights.

    This package is being used in different production projects and it is in constant evolution based on the needs of these projects. If you find some error that is not handled yet or that does not provide a great context, please open an issue or pull request ๐Ÿ™

    Source code(tar.gz)
    Source code(zip)
Owner
Enzo Ferey
Learning to be the developer you want to work with | React.js lover | Maker | Crypto
Enzo Ferey
Build a Full Stack Marketplace on Ethereum with React, Solidity, Hardhat, and Ethers.js

Building a Digital Marketplace on Ethereum The technologies used in this workshop are React, Next.js, Tailwind CSS, HardHat, Solidity, and Ethers. Get

Nader Dabit 114 Nov 15, 2022
A web3 starter project using Typescript, Hardhat, ethers.js and @web3-react

Starter React Typescript Ethers.js Hardhat Project This repo contains a Hardhat and React Dapp starter project. The React Dapp in the frontend dir of

ChainShot 39 Dec 31, 2022
A Bed and Breakfast dApp run on Ethereum. Includes a token + schedule system (Solidity) and full front-end (React + ethers.js) built with Hardhat.

Hotel ETH - Watch Demo Video Hotel ETH A (fictional) Bed-and-Breakfast run on Ethereum Come Book a Room on Kovan or Rinkeby Networks View the Demo ยป C

Ryan Lambert 20 Aug 20, 2022
Library for interacting with RMM protocol through ethers.js.

?? rmm-ethers Easily connect and transact with RMM protocol. ?? Features ?? Deploy RMM protocol โšก๏ธ Easily connect to an RMM deployment ?? Create RMM p

Primitive 14 Nov 13, 2022
A comprehensive collection of useful tools developed with the help of Ethers.js to interact with the Ethereum Blockchain to develop great DeFi apps as quickly and easily as possible.

hudi-packages-ethersfactory How to install Installing with npm For more information on using npm check out the docs here. npm i @humandataincome/ether

HUDI 6 Mar 30, 2022
Decentralized twitter using Solidity, Ethereum, hardhat, ethers, IPFS, Next.JS, TypeScript, TailwindCSS.

DWITTER: Decentralized Twitter Check out the deployed version of this app at https://dwtr.wajeshubham.in Transactions on Ethereum are slow. Therefore,

Shubham Waje 12 Sep 2, 2022
Flashbots Ethers TypeScript example for Node.js and browser

Flashbots Ethers Example This project shows how to use Ethers to interact with Flashbots from JavaScript/TypeScript. The examples can be run in Node.j

Chris Hager 34 Jun 28, 2022
Introductory fullstack ethereum dapp using: solidity, hardhat, react.js, ethers.js

Intro to Fullstack Ethereum Development Check out deployed dapp here! (Make sure you're connected to the Rinkeby Testnet) This article will help you e

Christian Chiarulli 77 Dec 21, 2022
A guide to showcase use cases for web3.js and ethers.js libraries

Use case using web3.js and ethers.js The purpose of these scripts is to show how to build common cases of interaction with the blockchain using web3.j

ProtoFire 6 Aug 31, 2022
Decentralized Social Media. Built using Next.js. Web3 integration with Moralis, Metamask and Ethers.js. Also uses Lens Protofcol to get the profile data.

DecentraGram Decentralized Social Media. Built using Next.js. Web3 integration with Moralis, Metamask and Ethers.js. Also uses Lens Protofcol to get t

Didier Peran Ganthier 8 Dec 20, 2022
Sample project with: NextJS + Typescript + ReduxToolKit + Tailwind + Ethers

This is a Next.js project bootstrapped with create-next-app. Small app which shows last mined Blocks in real time on BSC and its transactions in backg

MBJ 2 Oct 9, 2022
This is a test parser which can automatically parse the tests in from websites like codeforces, codechef, atcoder etc.

โœ” Sublime test parser This is a test parser which can automatically parse the tests in from websites like codeforces, codechef, atcoder etc. See how i

Prakhar Rai 15 Aug 6, 2022
Twitter Text Libraries. This code is used at Twitter to tokenize and parse text to meet the expectations for what can be used on the platform.

twitter-text This repository is a collection of libraries and conformance tests to standardize parsing of Tweet text. It synchronizes development, tes

Twitter 2.9k Jan 8, 2023
Auto-Fix Hundreds of Grammarly Errors With This Script

This script automatically applies your Grammarly suggestions. Use case: Large document with 100+ errors How to use: Go to Grammarly Web app Go to Edit

null 48 Jan 3, 2023
Github action to parse OWNERS files and outputs random reviewers

Get Owners Github Action Do you want to have all the approvers and reviewers without having strange scripts in your actions? Do you want to have rando

Ugo Palatucci 3 Oct 22, 2022
A set of connectors to describe, parse and process the data sources provided by websites and social networks

HUDI-PACKAGE-CONNECTORS What is this repository for? A set of connectors to describe, parse and process the data sources provided by websites and soci

HUDI 8 Aug 5, 2022
Beautiful errors for Remix, both in browser and console

Rekindled Beautiful errors for Remix, both in browser and console. This project is inspired by php's ignition. I am personally in love with the idea o

FYN Software 22 Nov 22, 2022
In Your Face shows you Doom 'Ouch Faces' that correlate to the number of errors in your code!

In Your Face Watch how I made this extension on YouTube here In Your Face is a VS Code extension that shows you Doom 'Ouch Faces' that correlate to th

Virej Dasani 125 Dec 25, 2022
A simple library that I use for web scraping. Uses htmlparser2 to parse dom.

Docpa A simple library that I use for web scraping. Uses htmlparser2 to parse dom. Usage const Docpa = require("docpa") const doc = new Docpa(`<html>

Roshan Acharya 2 Jan 21, 2022