web3-error-humanizer

A local-first developer toolkit for Web3 errors -- structured classification, severity, actionable suggestions, and 790+ local patterns. Optional AI fallback.

Why?

When a DEX swap fails, your users see this:

execution reverted: INSUFFICIENT_OUTPUT_AMOUNT

Error: Pancake: K

ContractFunctionRevertedError: UniswapV2: LOCKED

With this library, they see this instead:

Price moved too much. Try increasing your slippage tolerance.

Low liquidity for this pair. Try a smaller swap amount.

This pair is currently locked. Try again shortly.

One import. Zero config. No API key required.

import { humanizeError } from "web3-error-humanizer";

const message = humanizeError(error);
// "Price moved too much. Try increasing your slippage tolerance."

EVM-only apps can import a smaller dictionary (generic + wallets + EVM + bridges). The default import still includes every chain.

import { humanizeErrorDetailed } from "web3-error-humanizer/evm";

Or get full structured output for building smart UIs:

import {
  humanizeErrorDetailed,
  isRecoverable,
  classifyError,
} from "web3-error-humanizer";

const result = humanizeErrorDetailed(error);
// {
//   message:     "Price moved too much. Try increasing your slippage tolerance.",
//   category:    "slippage",
//   severity:    "warning",
//   suggestion:  "Increase your slippage tolerance or try a smaller amount.",
//   recoverable: true,
//   source:      "local",
//   matchedKey:  "INSUFFICIENT_OUTPUT_AMOUNT",
//   rawMessage:  "INSUFFICIENT_OUTPUT_AMOUNT"
// }

if (result.category === "insufficient_allowance") showApproveButton();
if (result.category === "chain_mismatch") showSwitchNetworkButton();
if (result.recoverable) showRetryButton();

Apps with i18n should keep the English message as a fallback and map result.category or result.matchedKey through their own translator.

Why Developers Like It

• Useful without AI -- the default import is local-only, fast, and has zero runtime dependencies
• Structured, not just pretty strings -- categories, severity, suggestions, and recoverability let you build real product UX
• Optional AI instead of forced AI -- unknown errors can use the /ai entry point, but the core package never requires an API key
• Safe to bundle -- ESM + CommonJS exports and TypeScript types. Use /evm or /solana to skip unused chain dictionaries.

Features

• 790+ local error patterns -- exact, token, and scored substring matches, no API calls needed
• Structured error output -- category, severity, suggestion, recoverability, and matchedKey for every error
• 16 error categories -- user_rejection, insufficient_funds, slippage, gas, network, bridge, and more
• Zero dependencies -- the main entry point has no runtime dependencies
• Isolated instances -- createHumanizer({ chain, patterns }) for Next.js, tests, and multi-chain apps
• AI fallback -- unknown errors optionally analyzed by GPT-4o-mini (separate import, not for swap confirm)
• viem-compatible -- deep error extraction for nested blockchain errors (viem is optional)
• Extensible -- add your own patterns with createHumanizer({ patterns }) or process-wide addPattern()
• Dual module -- ESM and CommonJS, full TypeScript types included

Supported Protocols

Protocol	Errors Covered
Uniswap V2/V3/V4	K, INSUFFICIENT_OUTPUT_AMOUNT, EXPIRED, LOCKED, SPL, Hook errors, and more
PancakeSwap	K, INSUFFICIENT_LIQUIDITY, TRANSFER_FAILED, etc.
SushiSwap	K, INSUFFICIENT_OUTPUT_AMOUNT, EXPIRED
Curve Finance	Insufficient output/input, slippage, math errors
Balancer	Insufficient liquidity, paused pools, swap disabled
1inch	minReturn, ReturnAmountIsNotEnough, insufficient liquidity
DODO	Insufficient output/input, liquidity errors
KyberSwap	Insufficient output/input, liquidity errors
Aave V3	VL_* errors (borrowing, supply caps, health factors)
Account Abstraction (ERC-4337)	AA10-AA51 (EntryPoint errors, paymaster, validation)
Solana / Jupiter	Program errors, slippage, compute budget, blockhash
LayerZero	Bridge errors, token unavailability, message blocking
Li.Fi / Stargate	Route errors, slippage, amount limits
Arbitrum / Optimism	Retryable tickets, L2 execution, fee errors
MetaMask/EIP-1193	4001, 4100, 4900, -32603, and all standard codes
WalletConnect/Reown	USER_REJECTED, SESSION_EXPIRED, APKT001-APKT010
Gnosis Safe	GS000-GS031 (initialization, signatures, owners)
ERC20/721/1155	ERC-6093 standard errors, allowance, balance, transfer
Gas/Network	Underpriced, out of gas, timeout, replacement errors
Hardware Wallets	Ledger, Trezor connection and signing errors
Multi-chain Wallets	Phantom, TronLink, Sui, Aptos, TON, Bitcoin wallets

Installation

npm install web3-error-humanizer

Also works with pnpm add and yarn add. Zero dependencies for the main entry point. Install openai separately if you want AI fallback. The published package runs on Node.js >= 20. Publishing a release with semantic-release currently needs Node.js >= 22.14.

Quick Start

Local Only (No API Key Required)

import { humanizeError } from "web3-error-humanizer";

try {
  await contract.write.swap([...]);
} catch (error) {
  const message = humanizeError(error);
  console.log(message);
  // "Price moved too much. Try increasing your slippage tolerance."
}

With AI Fallback

import { Web3ErrorHumanizer } from "web3-error-humanizer/ai";

const humanizer = new Web3ErrorHumanizer({
  openaiApiKey: process.env.OPENAI_API_KEY!,
});

try {
  await contract.write.swap([...]);
} catch (error) {
  const message = await humanizer.humanize(error);
  // Local match -> instant response
  // Unknown error -> AI generates response
}

Requires openai as a peer dependency. The /ai entry point only sends sanitized error text to OpenAI when you configure an API key. The default import never makes network requests.

Toolkit API

Error Categories

Every matched error is classified into one of 16 categories:

Category	Description	Severity	Recoverable
user_rejection	User cancelled/rejected in wallet	info	Yes
insufficient_funds	Not enough balance or gas	error	Yes
insufficient_allowance	Token needs approval first	warning	Yes
slippage	Price moved beyond tolerance	warning	Yes
liquidity	Pool has no/low liquidity	error	Yes
gas	Gas estimation or pricing failed	error	Yes
nonce	Transaction ordering issue	warning	Yes
network	RPC / connection problems	error	Yes
contract_error	Smart contract reverted	error	No
timeout	Transaction/request timed out	warning	Yes
wallet_connection	Wallet not connected/locked	error	Yes
chain_mismatch	Wrong network selected	warning	Yes
protocol_limit	Supply/borrow caps, paused state	error	Yes
signature	Signing failed	error	Yes
bridge	Cross-chain bridge errors	error	Yes
unknown	Unrecognized error	error	No

Building Smart Error UIs

import {
  humanizeErrorDetailed,
  classifyError,
  isRecoverable,
  getSuggestion,
} from "web3-error-humanizer";

try {
  await sendTransaction();
} catch (err) {
  const result = humanizeErrorDetailed(err);

  showToast(result.message);

  if (result.category === "insufficient_allowance") {
    showApproveButton();
  } else if (result.category === "chain_mismatch") {
    showSwitchNetworkButton();
  } else if (result.category === "insufficient_funds") {
    showAddFundsLink();
  } else if (result.recoverable) {
    showRetryButton();
  }

  analytics.track("tx_error", {
    category: result.category,
    severity: result.severity,
    recoverable: result.recoverable,
    raw: result.rawMessage,
  });
}

Quick Classification (No Humanization)

import {
  classifyError,
  isRecoverable,
  getSuggestion,
  getErrorSeverity,
} from "web3-error-humanizer";

const category = classifyError(error); // "slippage"
const canRetry = isRecoverable(error); // true
const nextStep = getSuggestion(error); // "Increase your slippage tolerance or try a smaller amount."
const severity = getErrorSeverity(error); // "warning"

Isolated instance (recommended for apps and tests)

addPattern() mutates a process-wide registry. Prefer createHumanizer() when you need custom patterns, a chain hint, or test isolation:

import { createHumanizer } from "web3-error-humanizer";

const humanizer = createHumanizer({
  chain: "evm",
  fallbackMessage: "Swap failed. Please try again.",
  patterns: {
    MY_DEX_ERROR: { message: "This pool is paused.", category: "protocol_limit" },
  },
});

const result = humanizer.humanizeDetailed(error);

chain only narrows protocol-specific codes (for example Aave 26 vs Jupiter 0x1771). Shared wallet and rejection patterns still match. Omit chain to use the full dictionary.

Wagmi / viem

import { humanizeErrorDetailed } from "web3-error-humanizer";

try {
  await walletClient.writeContract({ /* ... */ });
} catch (error) {
  const result = humanizeErrorDetailed(error);
  toast.error(result.message);
  if (result.category === "insufficient_allowance") openApprove();
  else if (result.category === "chain_mismatch") openSwitchNetwork();
  else if (result.recoverable) showRetry();
}

Usage with Context

Provide swap context for smarter AI responses. Do not call /ai on the swap confirm path -- keep unmatched errors on the generic fallback:

const message = await humanizer.humanize(error, {
  fromToken: "USDC",
  toToken: "PEPE",
  amount: "1000",
  slippage: "0.5%",
  network: "Ethereum",
});
// "PEPE's price is changing rapidly. Increase slippage to 1-2% or try a smaller amount."

API Reference

Function	Returns	Description
humanizeError(error, fallback?)	string	Human-friendly message, or fallback
humanizeErrorLocal(error)	string | null	Human-friendly message, or null if no match
humanizeErrorDetailed(error, fallback?)	HumanizedResult	Rich object with category, severity, suggestion
classifyError(error)	ErrorCategory	Error category without humanizing
isRecoverable(error)	boolean	Whether the user can fix this
getSuggestion(error)	string	Actionable next step
getErrorSeverity(error)	ErrorSeverity	"error" / "warning" / "info"
extractRawMessage(error)	string	Raw message from any error shape
createHumanizer(options?)	LocalHumanizer	Isolated registry with optional chain and patterns
addPattern(key, msg, category?)	void	Add a custom pattern at runtime (process-wide)
addPatterns(map)	void	Batch add patterns (process-wide)
resetCustomPatterns()	void	Restore built-ins and rebuild the lookup index
getLocalErrorCount()	number	Total patterns in registry
hasLocalPattern(key)	boolean	Check if a pattern exists
getLocalPatterns()	string[]	List all pattern keys

Class-based (AI fallback): Import Web3ErrorHumanizer from web3-error-humanizer/ai. See API.md for full documentation with examples.

How It Works

flowchart TD
    A["Caught Error"] --> B["Extract Message"]
    B --> C{"Local Dictionary\n790+ patterns"}
    C -->|match found| D["Instant Response\nfree, less than 1ms"]
    C -->|no match| E{"AI configured?"}
    E -->|yes| F["OpenAI API\npaid, ~500ms"]
    E -->|no| G["Fallback Message"]

Loading

1. Extract -- Pulls the raw error message from viem BaseError, ethers error objects, EIP-1193 codes, or plain strings
2. Match locally -- exact phrase/code, then embedded RPC/hex tokens, then scored substring matches (category priority, then length)
3. AI fallback -- Optional /ai import only. Unknown errors can stay on the generic fallback.
4. Fallback -- Returns a configurable default message if nothing else matches

Limitations

• Local matching is only as good as the current dictionary. Unknown protocol-specific errors still need new patterns. Leaving them on the fallback is fine.
• Generic single-word keys such as TIMEOUT are exact-only so they do not hijack unrelated messages.
• addPattern() and addPatterns() mutate a shared in-memory registry for the current process. Prefer createHumanizer({ patterns }) in apps and tests. resetCustomPatterns() restores built-ins and rebuilds the index.
• If you use web3-error-humanizer/ai, do not pass secrets in error context that you would not want sent to your model provider.
• For high-volume AI usage, consider caching responses for repeated errors.

Adopting later in an existing DEX (Houdini-style)

If the app already has chain-aware helpers and t() keys, do not replace that layer in one shot:

1. Call humanizeErrorDetailed() or createHumanizer({ chain }).humanizeDetailed() beside the existing parser.
2. If the app already has a translation key, keep it.
3. Otherwise use category / matchedKey to drive t() and CTAs.
4. Keep /ai off the swap confirm path.

More

• Full API Reference -- every function documented with examples and types
• Framework Examples -- Next.js, Node.js, CommonJS integration patterns
• Contributing Guide -- how to add error patterns and submit PRs

License

MIT © halilatilla