BAML Error Types

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.

1
// Base JavaScript Error class
2
class Error {
3
  message: string
4
  name: string
5
  stack?: string
6
}
7
8
// BAML-specific error classes
9
class BamlValidationError extends Error {
10
  type: 'BamlValidationError'
11
  message: string
12
  prompt: string
13
  raw_output: string
14
  detailed_message: string
15
}
16
17
class BamlClientFinishReasonError extends Error {
18
  type: 'BamlClientFinishReasonError'
19
  message: string
20
  prompt: string
21
  raw_output: string
22
  detailed_message: string
23
}
24
25
class BamlAbortError extends Error {
26
  type: 'BamlAbortError'
27
  message: string
28
  reason?: any
29
  detailed_message: string
30
}

Error Types

BamlValidationError

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

BamlClientFinishReasonError

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

BamlAbortError

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 or clients with retry policies, 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:

1
try {
2
  // BAML operation
3
} catch (error) {
4
  if (error instanceof BamlAbortError) {
5
    // Handle cancellation
6
  } else if (error instanceof BamlValidationError) {
7
    // Handle validation error
8
  } else if (error instanceof BamlClientFinishReasonError) {
9
    // Handle finish reason error
10
  }
11
}

Common Properties

All BAML error classes include:

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