> Version notice: This site documents BAML v0, the legacy DSL. BAML v1 is a separate, fully featured programming language in public beta. If the user intends to use BAML v1, ignore this site's content and use the BAML v1 documentation instead. If the intended version is unclear, clarify it before using this page.
> For clean Markdown of any page, append .md to the page URL. For the complete documentation index, see https://docs.boundaryml.com/llms.txt. For MCP access, connect to https://docs.boundaryml.com/_mcp/server.

# BAML Error Types

> Technical reference for BAML error handling classes

BAML provides a set of error classes for handling different error scenarios when working with LLMs. Each error type is designed to handle specific failure cases in the BAML runtime.

## Error Class Hierarchy

All BAML errors extend the base JavaScript `Error` class and include a literal `type` field for type identification.

**`Type Hierarchy`**

```typescript Type Hierarchy
// Base JavaScript Error class
class Error {
  message: string
  name: string
  stack?: string
}

// BAML-specific error classes
class BamlValidationError extends Error {
  type: 'BamlValidationError'
  message: string
  prompt: string
  raw_output: string
  detailed_message: string
}

class BamlClientFinishReasonError extends Error {
  type: 'BamlClientFinishReasonError'
  message: string
  prompt: string
  raw_output: string
  detailed_message: string
}

class BamlAbortError extends Error {
  type: 'BamlAbortError'
  message: string
  reason?: any
  detailed_message: string
}
```

## Error Types

### [BamlValidationError](./baml-validation-error)

Thrown when BAML fails to parse or validate LLM output. Contains the original prompt and raw output for debugging.

### [BamlClientFinishReasonError](./baml-client-finish-reason-error)

Thrown when an LLM terminates with a disallowed finish reason. Includes the original prompt and partial output received before termination.

### [BamlAbortError](./baml-abort-error)

Thrown when a BAML operation is cancelled via an abort controller. Contains an optional reason for the cancellation.

## Fallback Error Aggregation

When using [fallback clients](/ref/llm-client-strategies/fallback) or clients with [retry policies](/ref/llm-client-strategies/retry-policy), BAML attempts multiple client calls before finally failing. In these cases:

* The error **type** corresponds to the final (last) failed attempt
* The `message` field contains the error message from the final attempt
* The `detailed_message` field contains the **complete history** of all failed attempts

This allows you to debug the entire fallback chain while still getting a specific error type for the final failure.

## Type Guards

All BAML errors can be identified using TypeScript's `instanceof` operator:

**`Type Checking`**

```typescript Type Checking
try {
  // BAML operation
} catch (error) {
  if (error instanceof BamlAbortError) {
    // Handle cancellation
  } else if (error instanceof BamlValidationError) {
    // Handle validation error
  } else if (error instanceof BamlClientFinishReasonError) {
    // Handle finish reason error
  }
}
```

## Common Properties

All BAML error classes include:

**`type`** `string`

Literal type identifier specific to each error class.

---

**`message`** `string`

Human-readable error message describing the failure.

---

**`detailed_message`** `string`

Comprehensive error information that includes the complete history of all failed attempts when using fallback clients or retry policies. For single attempts, this typically contains the same information as `message` but may include additional debugging details.

---

For detailed information about each error type, refer to their individual reference pages.