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

1
from baml_client import b
2
from baml_py.errors import BamlError, BamlInvalidArgumentError, BamlClientError, BamlClientHttpError, BamlValidationError
3
from baml_py import BamlAbortError
4
5
try:
6
  b.CallFunctionThatRaisesError()
7
except BamlError as e:
8
  print(e)
9
10
11
try:
12
  b.CallFunctionThatRaisesError()
13
except 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)
20
  # Complete error history (includes fallback attempts)
21
  print(e.detailed_message)

BamlError

Base class for all BAML exceptions.

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.

BamlClientHttpError

Subclass of BamlClientError.

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

BamlClientFinishReasonError

Subclass of BamlClientError.

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

BamlValidationError

Subclass of BamlError.

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

BamlAbortError

Subclass of BamlError.

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

Handling Cancellation

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

1
from baml_client import b
2
from baml_py import AbortController, BamlAbortError
3
4
async 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.

LLM Fixup: Dealing with Validation Errors

Our parser is very forgiving, allowing for structured data parsing even in the presence of minor errors and thought tokens in the LLM response. However, certain types of errors are too ambiguous to handle without the help of an LLM.

In cases where your LLM is having trouble producing valid data from the output schema, you can use this ‘fixup’ recipe to get valid data:

1. Write a Fixup Function. For example, if your original function is called Foo and it returns MyClass:

1
function FixupFoo(errorMessage: string) -> MyClass {
2
    client GPT4o
3
    prompt #"
4
        Fix this malformed JSON. Preserve the same information.
5
6
        {{ ctx.output_format }}
7
8
        Original data and parse error:
9
        {{ errorMessage }}
10
    "#
11
}

2. Then call the fixup function from your client code in response to validation errors:

1
try:
2
    result = b.Foo(myData)
3
except Baml.ValidationError as e:
4
    result = b.FixupFoo(str(e))

Choosing a Model

LLMs are good at reconstituting data, so it is often possible to use a less powerful model for your fixup function than the model you used to produce the original data. The difficulty of producing valid JSON data depends on the complexity of the schema and the details of your data payload, so be sure to test your fixup function on realistic data payloads before moving to a smaller model.