viem-error-parser

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

Why

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.

Install

pnpm add viem-error-parser viem

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."
}

Documentation

The full docs live in ./docs:

• Getting started — install, Viem / Wagmi / React quick-starts.
• Registering custom ABIs — decode your contract's revert errors.
• The result shape — ParseResult discriminated union and type guards.
• The classifier — non-revert errors, full rule table, decoder pipeline.
• Advanced usage — AbiRegistry / ErrorDecoder by hand.
• TypeScript — branded types and the zero-runtime ./types entry.
• Bundle size — what tree-shaking actually removes.
• API reference — every public export.

A copy of the docs is also published as the GitHub Wiki.

Examples

Three runnable examples live under ./examples:

• examples/basic — Node script using forViem.
• examples/nextjs — Next.js App Router page with useErrorParser.
• examples/vite-react — Vite + React with forWagmi.

Contributing

See CONTRIBUTING.md. All contributors follow the Code of Conduct. Security issues should be reported per SECURITY.md.

License

MIT © 2026 Hanif Maulana (Isaac Newton)

Creator

Hanif Maulana (Isaac Newton)

• Website: eslint-ai-guardrails.vercel.app
• GitHub: github.com/isaacnewton123
• X: x.com/isaac_newton252
• Facebook: facebook.com/hanif.maulana.108
• LinkedIn: linkedin.com/in/hanif-maulana-210b4721b
• Instagram: instagram.com/hanifmaulana2

Support

If this library saves you from Viem/Wagmi error chaos, consider supporting development:

• Ko-fi: ko-fi.com/isaacnewton1
• Trakteer: trakteer.id/isaacnewton1/link
• GitHub: github.com/sponsors/isaacnewton123