BAML Error Types - Baml

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.

<CodeBlocks> ```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 }

</CodeBlocks>

## 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:

<CodeBlocks>
```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
  }
}

</CodeBlocks>

Common Properties

All BAML error classes include:

<ParamField path="type" type="string"

Literal type identifier specific to each error class. </ParamField>

<ParamField path="message" type="string"

Human-readable error message describing the failure. </ParamField>

<ParamField path="detailed_message" type="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. </ParamField>

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