> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://v3.viem.sh/api/mcp` to find what you need.

# Contract Errors

## Overview

The **ContractError** module provides errors for failed contract function execution.

[Contract Actions](/docs/actions/public/contract/read), including
[`Actions.contract.read`](/docs/actions/public/contract/read),
[`Actions.contract.write`](/docs/actions/wallet/contract/write), and
[`Actions.contract.simulate`](/docs/actions/public/contract/simulate), throw
`ContractError.ContractFunctionExecutionError`.

The error identifies the contract function. It includes the address, arguments, and sender when
those values are provided.

For an EVM revert, the error's `cause` is
`ContractError.ContractFunctionRevertedError`. Viem decodes the cause against the contract ABI.

Decoded data can contain an `Error(string)` reason, `Panic` code, or custom error arguments.

```ts twoslash
import { Actions, Client, ContractError, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abi } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })

try {
  await Actions.contract.simulate(client, {
    abi: Abi.from(['function mint(uint256 amount)']),
    address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
    args: [69420n],
    functionName: 'mint',
  })
} catch (error) {
  if (error instanceof ContractError.ContractFunctionExecutionError)
    console.log(error.functionName, error.args)
}
```

## Recipes

### Catching a Revert Reason

Inspect the error's `cause`. A revert produces `ContractFunctionRevertedError` with the decoded
`reason` and raw revert data.

```ts twoslash
import { Actions, Client, ContractError, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abi } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })

try {
  await Actions.contract.simulate(client, {
    abi: Abi.from(['function mint(uint256 amount)']),
    address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
    args: [69420n],
    functionName: 'mint',
  })
} catch (error) {
  if (error instanceof ContractError.ContractFunctionExecutionError) { // [!code focus]
    const revert = error.cause // [!code focus]
    if (revert instanceof ContractError.ContractFunctionRevertedError) // [!code focus]
      console.log(revert.reason) // [!code focus]
    // @log: 'Amount exceeds maximum mintable.'
  }
}
```

### Handling Custom Errors

When the ABI contains the custom error, `data` provides its decoded `name` and `args`. Otherwise,
the error provides the raw `signature`.

```ts twoslash
import { Actions, Client, ContractError, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abi } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })

try {
  await Actions.contract.simulate(client, {
    abi: Abi.from([
      'function mint(uint256 amount)',
      'error AmountTooLarge(uint256 amount)', // [!code focus]
    ]),
    address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
    args: [69420n],
    functionName: 'mint',
  })
} catch (error) {
  if (error instanceof ContractError.ContractFunctionExecutionError) {
    const revert = error.cause
    if (revert instanceof ContractError.ContractFunctionRevertedError) {
      console.log(revert.data?.name) // [!code focus]
      // @log: 'AmountTooLarge'
      console.log(revert.data?.args) // [!code focus]
      // @log: [69420n]
    }
  }
}
```

## `ContractError.fromError`

Converts a raw contract execution error to `ContractFunctionExecutionError`. When possible, the
function decodes the revert reason against the provided ABI.

Contract Actions call this function internally. Use it when you build a custom Contract Action.

### Usage

```ts twoslash
import { ContractError } from 'viem'
import { Abi } from 'viem/utils'

const abi = Abi.from(['function mint(uint256 amount)'])

declare const error: Error

const contractError = ContractError.fromError(error, {
  abi,
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  args: [69420n],
  functionName: 'mint',
})
```

### Parameters

#### error

* **Type:** `Error`

The raw error thrown while executing the contract function.

```ts twoslash
import { ContractError } from 'viem'
import { Abi } from 'viem/utils'

const abi = Abi.from(['function mint(uint256 amount)'])
declare const error: Error
// ---cut---
const contractError = ContractError.fromError(
  error, // [!code focus]
  { abi, args: [69420n], functionName: 'mint' },
)
```

The contract call context.

#### options.abi

* **Type:** `Abi | readonly unknown[]`

The contract ABI used to decode revert data.

```ts twoslash
import { ContractError } from 'viem'
import { Abi } from 'viem/utils'

declare const error: Error
// ---cut---
const contractError = ContractError.fromError(error, {
  abi: Abi.from(['function mint(uint256 amount)']), // [!code focus]
  functionName: 'mint',
})
```

#### options.address

* **Type:** `Address.Address`
* **Optional**

The contract address shown in the error context.

```ts twoslash
import { ContractError } from 'viem'
import { Abi } from 'viem/utils'

declare const error: Error
// ---cut---
const contractError = ContractError.fromError(error, {
  abi: Abi.from(['function mint(uint256 amount)']),
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', // [!code focus]
  functionName: 'mint',
})
```

#### options.args

* **Type:** `unknown`
* **Optional**

The function arguments shown in the error context.

```ts twoslash
import { ContractError } from 'viem'
import { Abi } from 'viem/utils'

declare const error: Error
// ---cut---
const contractError = ContractError.fromError(error, {
  abi: Abi.from(['function mint(uint256 amount)']),
  args: [69420n], // [!code focus]
  functionName: 'mint',
})
```

#### options.docsPath

* **Type:** `string`
* **Optional**

The documentation path appended to the error.

```ts twoslash
import { ContractError } from 'viem'
import { Abi } from 'viem/utils'

declare const error: Error
// ---cut---
const contractError = ContractError.fromError(error, {
  abi: Abi.from(['function mint(uint256 amount)']),
  docsPath: '/docs/contracts/mint', // [!code focus]
  functionName: 'mint',
})
```

#### options.functionName

* **Type:** `string`

The name of the called contract function.

```ts twoslash
import { ContractError } from 'viem'
import { Abi } from 'viem/utils'

declare const error: Error
// ---cut---
const contractError = ContractError.fromError(error, {
  abi: Abi.from(['function mint(uint256 amount)']),
  functionName: 'mint', // [!code focus]
})
```

#### options.sender

* **Type:** `Address.Address`
* **Optional**

The transaction sender shown in the error context.

```ts twoslash
import { ContractError } from 'viem'
import { Abi } from 'viem/utils'

declare const error: Error
// ---cut---
const contractError = ContractError.fromError(error, {
  abi: Abi.from(['function mint(uint256 amount)']),
  functionName: 'mint',
  sender: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', // [!code focus]
})
```

### Return Value

`ContractError.ContractFunctionExecutionError`

The wrapped error. Its `cause` is a `ContractFunctionRevertedError` (decoded revert), a `ContractFunctionZeroDataError` (the call returned `0x`), or the original error.

## Error Classes

| Error | Description |
| --- | --- |
| `ContractError.ContractFunctionExecutionError` | A contract function failed to execute. Carries `abi` and `functionName`, with optional `args`, `contractAddress`, and `sender`. The underlying failure is available as `cause`. |
| `ContractError.ContractFunctionRevertedError` | A contract function reverted. Carries the decoded `data` (`name`, `args`), the `reason` string, the `raw` revert data, and the `signature` when the selector is not on the ABI. |
| `ContractError.ContractFunctionZeroDataError` | A contract function call returned no data (`0x`), for example when the address is not a contract. |
| `ContractError.RawContractError` | A raw contract error carrying the revert `data` returned by a node. |