Introduction

Decode Viem and Wagmi errors into clean, human-readable messages — including custom revert reasons from your own ABIs.

Why viem-error-parser?

Viem and Wagmi throw deeply-nested error chains. Pulling a useful message out of one — and decoding custom revert MyError(uint256) payloads on top of Error(string) and Panic(uint256) — is verbose and easy to get wrong.

viem-error-parser does the boring part:

• Walks the cause chain (and errors[]) safely with cycle and depth guards.
• Extracts revert data from every common shape: data, rawData, returnData, output, or hex embedded in messages.
• Decodes the two standard Solidity revert types out of the box.
• Decodes your custom errors when you register your ABIs.
• Classifies non-revert problems too — user rejection, gas, network, RPC, EIP-1193 codes, and more.
• Ships ESM + CJS + types, tree-shakable, with a react subpath for a useErrorParser hook.

It is a thin (~22 KB ESM) layer on top of viem. The only runtime dependency is viem itself.

30-second example

import { forViem } from 'viem-error-parser';

const decoder = forViem();

try {
  await walletClient.writeContract({ /* ... */ });
} catch (error) {
  console.error(decoder.decode(error).message);
  // "ERC20InsufficientBalance(sender=0x..., balance=5n, needed=100n)"
  // or "The transaction was rejected by the user."
}

Pages

Repository

• Source: github.com/isaacnewton123/viem-error-parser
• npm: npmjs.com/package/viem-error-parser
• Issues: github.com/isaacnewton123/viem-error-parser/issues