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.

// 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

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:

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:

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