> **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.

# Base Error

## Overview

[`Errors.BaseError`](#errorsbaseerror) is the base error class inherited by all errors thrown by
Viem.

It extends Ox's `BaseError`, so every Viem error is also an Ox error. The
`instanceof Errors.BaseError` check works across the stack.

Ox errors become the `cause` without another wrapper. Documentation origin and version attribution
use the values from [`Errors.setConfig`](/docs/errors/configuration).

```ts twoslash
import { Errors } from 'viem'

throw new Errors.BaseError('An error occurred.', {
  docsPath: '/docs/errors',
  metaMessages: ['Reason: example'],
})
```

## Recipes

### Attaching a Cause

Wrap a lower-level error when you want callers to inspect the original failure.

```ts twoslash
import { Errors } from 'viem'

const cause = new Error('boom') // [!code focus]

throw new Errors.BaseError('An error occurred.', { cause }) // [!code focus]
```

### Adding Meta Messages

Add meta messages when you need extra lines between the message and detail block.

```ts twoslash
import { Errors } from 'viem'

throw new Errors.BaseError('An error occurred.', {
  metaMessages: ['Reason: example'], // [!code focus]
})
```

### Linking to Docs

Set a docs path when the error should render a `See: <url>` line.

```ts twoslash
import { Errors } from 'viem'

throw new Errors.BaseError('An error occurred.', {
  docsPath: '/docs/errors', // [!code focus]
})
```

### Overriding Details

Override details when you want to show a precise explanation instead of deriving it from the cause.

```ts twoslash
import { Errors } from 'viem'

throw new Errors.BaseError('An error occurred.', {
  details: 'The RPC returned an invalid response.', // [!code focus]
})
```

## `Errors.BaseError`

The base error class inherited by all errors thrown by Viem.

### Usage

```ts twoslash
import { Errors } from 'viem'

throw new Errors.BaseError('An error occurred.', {
  docsPath: '/docs/errors',
  metaMessages: ['Reason: example'],
})
```

### Parameters

#### shortMessage

* **Type:** `string`

The short, human-readable error message.

```ts twoslash
import { Errors } from 'viem'
// ---cut---
throw new Errors.BaseError('An error occurred.') // [!code focus]
```

#### options.cause

* **Type:** `Error`

An error (Viem, ox, or foreign) to attach as the failure cause.

```ts twoslash
import { Errors } from 'viem'

const cause = new Error('boom')
// ---cut---
throw new Errors.BaseError('An error occurred.', {
  cause, // [!code focus]
})
```

#### options.details

* **Type:** `string`

Details of the error (derived from `cause` when omitted).

```ts twoslash
import { Errors } from 'viem'
// ---cut---
throw new Errors.BaseError('An error occurred.', {
  details: 'The RPC returned an invalid response.', // [!code focus]
})
```

#### options.docsOrigin

* **Type:** `string`

Docs origin override (defaults to the configured origin).

```ts twoslash
import { Errors } from 'viem'
// ---cut---
throw new Errors.BaseError('An error occurred.', {
  docsOrigin: 'https://viem.sh', // [!code focus]
})
```

#### options.docsPath

* **Type:** `string`

Docs path appended to the origin and rendered as `See: <url>`.

```ts twoslash
import { Errors } from 'viem'
// ---cut---
throw new Errors.BaseError('An error occurred.', {
  docsPath: '/docs/errors', // [!code focus]
})
```

#### options.metaMessages

* **Type:** `readonly (string | undefined)[]`

Meta messages rendered between the short message and the detail block.

```ts twoslash
import { Errors } from 'viem'
// ---cut---
throw new Errors.BaseError('An error occurred.', {
  metaMessages: ['Reason: example'], // [!code focus]
})
```

#### options.version

* **Type:** `string`

Version attribution override (defaults to the configured version).

```ts twoslash
import { Errors } from 'viem'
// ---cut---
throw new Errors.BaseError('An error occurred.', {
  version: 'viem@3.0.0', // [!code focus]
})
```

### Return Value

`Errors.BaseError`

A `BaseError` instance with `name: 'BaseError'` and the resolved `metaMessages`.