BAML Basics

Error Handling

When BAML raises an exception, it will be an instance of a subclass of BamlError. This allows you to catch all BAML-specific exceptions with a single except block.

Example

1from baml_client import b
2from baml_py.errors import BamlError, BamlInvalidArgumentError, BamlClientError, BamlClientHttpError, BamlValidationError
3from baml_py import BamlAbortError
4
5try:
6  b.CallFunctionThatRaisesError()
7except BamlError as e:
8  print(e)
9
10
11try:
12  b.CallFunctionThatRaisesError()
13except BamlValidationError as e:
14  # The original prompt sent to the LLM
15  print(e.prompt)
16  # The LLM response string
17  print(e.raw_output)
18  # A human-readable error message
19  print(e.message)

BamlError

Base class for all BAML exceptions.

message
string

A human-readable error message.

BamlInvalidArgumentError

Subclass of BamlError.

Raised when one or multiple arguments to a function are invalid.

BamlClientError

Subclass of BamlError.

Raised when a client fails to return a valid response.

In the case of aggregate clients like fallback or those with retry_policy, only the last client’s error is raised.

BamlClientHttpError

Subclass of BamlClientError.

Raised when the HTTP request made by a client fails with a non-200 status code.

status_code
int

The status code of the response.

Common status codes are:

  • 1: Other
  • 2: Other
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 429: Too Many Requests
  • 500: Internal Server Error

BamlClientFinishReasonError

Subclass of BamlClientError.

Raised when the finish reason of the LLM response is not allowed.

finish_reason
string

The finish reason of the LLM response.

message
string

An error message.

prompt
string

The original prompt that was sent to the LLM, formatted as a plain string. Images sent as base64-encoded strings are not serialized into this field.

raw_output
string

The raw text from the LLM that failed to parse into the expected return type of a function.

BamlValidationError

Subclass of BamlError.

Raised when BAML fails to parse a string from the LLM into the specified object.

raw_output
string

The raw text from the LLM that failed to parse into the expected return type of a function.

message
string

The parsing-related error message.

prompt
string

The original prompt that was sent to the LLM, formatted as a plain string. Images sent as base64-encoded strings are not serialized into this field.

BamlAbortError

Subclass of BamlError.

Raised when a BAML operation is cancelled via an abort controller.

message
string

A message describing why the operation was aborted.

reason
any

Optional additional context about the cancellation. This can be any value provided when calling the abort() method.

Handling Cancellation

When operations are cancelled via abort controllers, specific errors are thrown:

1from baml_client import b
2from baml_py import AbortController, BamlAbortError
3
4async def example():
5    controller = AbortController()
6    
7    # Cancel after 5 seconds
8    async def cancel_after_timeout():
9        await asyncio.sleep(5)
10        controller.abort('timeout')
11    
12    asyncio.create_task(cancel_after_timeout())
13    
14    try:
15        result = await b.ExtractData(
16            input_text,
17            baml_options={"abort_controller": controller}
18        )
19    except BamlAbortError as e:
20        if e.reason == 'timeout':
21            print("Operation timed out after 5 seconds")
22        else:
23            print(f"Operation was cancelled: {e.message}")
24    except BamlValidationError as e:
25        print(f"Validation failed: {e.message}")

For more information on using abort controllers, see the Abort Controllers guide.