---
url: 'https://adk.nht.io/api/@nhtio/adk/factories/classes/BaseException.md'
description: Base class for all structured exceptions in the ADK.
---

# Class: BaseException

Defined in: [lib/classes/base\_exception.ts:16](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L16)

Base class for all structured exceptions in the ADK.

## Remarks

Subclasses should declare static `code`, `status`, `fatal`, and optionally `help` to avoid
repeating those values on every instance. Instance-level options always take precedence over
static defaults, so a single exception class can still be thrown with per-site overrides when
needed.

The runtime cross-realm guard is inlined here rather than imported from `../utils/guards`
to break a circular-import chain: `guards` depends on `validation`, which extends
`BaseException`. Importing the shared `isInstanceOf` helper into this file would create a
load-order cycle that leaves `BaseException` undefined when `ValidationException extends
BaseException` evaluates.

## Extends

* `Error`

## Extended by

* [`ValidationException`](../../exceptions/classes/ValidationException.md)

## Constructors

### Constructor

```ts
new BaseException(message?: string, options?: ErrorOptions & {
  code?: string;
  fatal?: boolean;
  status?: number;
}): BaseException;
```

Defined in: [lib/classes/base\_exception.ts:96](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L96)

#### Parameters

| Parameter  | Type                                                                                | Description                                                                                                                                    |
| ---------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `message?` | `string`                                                                            | Human-readable error message. Falls back to the static `message` on the subclass if omitted.                                                   |
| `options?` | `ErrorOptions` & { `code?`: `string`; `fatal?`: `boolean`; `status?`: `number`; } | Standard `ErrorOptions` extended with `code`, `status`, and `fatal` overrides. Static defaults on the subclass are used when these are absent. |

#### Returns

`BaseException`

#### Overrides

```ts
Error.constructor;
```

## Properties

| Property                                 | Modifier | Type      | Description                                                                             | Overrides    | Defined in                                                                                                                |
| ---------------------------------------- | -------- | --------- | --------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
|  `code?`       | `public` | `string`  | Machine-readable error code for narrowing exception-handling logic.                     | -            | [lib/classes/base\_exception.ts:78](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L78) |
|  `fatal?`     | `public` | `boolean` | When `true`, the ADK treats this error as unrecoverable and should halt the agent loop. | -            | [lib/classes/base\_exception.ts:88](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L88) |
|  `help?`       | `public` | `string`  | Human-readable guidance for resolving or reporting this error.                          | -            | [lib/classes/base\_exception.ts:73](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L73) |
|  `name`        | `public` | `string`  | Name of the class that raised the exception.                                            | `Error.name` | [lib/classes/base\_exception.ts:68](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L68) |
|  `status?`   | `public` | `number`  | HTTP status code associated with this error.                                            | -            | [lib/classes/base\_exception.ts:83](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L83) |
|  `code?`     | `static` | `string`  | Default machine-readable error code inherited by all instances.                         | -            | [lib/classes/base\_exception.ts:51](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L51) |
|  `fatal?`   | `static` | `boolean` | Whether exceptions of this class are fatal by default.                                  | -            | [lib/classes/base\_exception.ts:59](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L59) |
|  `help?`     | `static` | `string`  | Default help text inherited by all instances unless overridden at the throw site.       | -            | [lib/classes/base\_exception.ts:47](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L47) |
|  `message?` | `static` | `string`  | Default message used when no message is supplied to the constructor.                    | -            | [lib/classes/base\_exception.ts:63](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L63) |
|  `status?` | `static` | `number`  | Default HTTP status code inherited by all instances.                                    | -            | [lib/classes/base\_exception.ts:55](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L55) |

## Accessors

### \[toStringTag]

#### Get Signature

```ts
get toStringTag: string;
```

Defined in: [lib/classes/base\_exception.ts:130](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L130)

##### Returns

`string`

## Methods

### toString()

```ts
toString(): string;
```

Defined in: [lib/classes/base\_exception.ts:134](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L134)

Returns a string representation of an object.

#### Returns

`string`

***

### isBaseException()

```ts
static isBaseException(value: unknown): value is BaseException;
```

Defined in: [lib/classes/base\_exception.ts:29](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/base_exception.ts#L29)

Returns `true` if `value` is a BaseException instance.

#### Parameters

| Parameter | Type      | Description        |
| --------- | --------- | ------------------ |
| `value`   | `unknown` | The value to test. |

#### Returns

`value is BaseException`

`true` when `value` is a BaseException instance.

#### Remarks

Performs cross-realm-safe detection: tries `instanceof`, then `Symbol.hasInstance`, then
constructor-name comparison. The ADK does not export the `BaseException` class itself
as a constructable value — use this guard plus the BaseException type for runtime
detection and TypeScript narrowing.