Errors

All Bridle-raised errors descend from BridleError. Catching it gives you one seam for everything the library throws.

from bridle import (
    BridleError,
    ConfigurationError,
    LoopExhaustedError,
    ModelError,
    SchemaSatisfactionError,
    TimeoutError,
    TokenBudgetExceededError,
    ToolExecutionError,
)

BridleError

Base class. Subclass of Exception. Catch this to handle anything Bridle raises in one place.

SchemaSatisfactionError

The model could not produce output matching the requested schema after max_schema_retries.

Raised from step, branch, loop, and any agent that resolves them.

ToolExecutionError

A tool raised and the tool was decorated with raise_on_error=True.

The __cause__ chain is set, so raise from introspection works.

ModelError

The provider failed, or max_turns was exhausted before the model called __bridle_return__.

No structured attributes — the message describes what happened. Wraps SDK-level exceptions via __cause__ when the failure originates in the provider.

LoopExhaustedError

A loop hit max_iterations before its predicate returned True.

Catch to fall back to partial results.

TimeoutError

A wrapped call exceeded its deadline. Not the same as builtins.TimeoutError — this is bridle.TimeoutError, a subclass of BridleError.

Raised from the timeout wrapper.

ConfigurationError

A required piece of configuration was missing or invalid. Common causes:

• No model resolved at any of the three layers — fix with bridle.configure(model=...), @agent(model=...), or with_model(call, ...).
• No model client registered — call bridle.models.anthropic.install() (or your own adapter's set_model_client).
• loop(... until=None) or loop(... max_iterations=0).
• retry(... attempts=0).

The message lists the fix when there are multiple options.

TokenBudgetExceededError

An agent's token_budget was exhausted mid-run. Usage accumulates across model_response events; the next step that would exceed the budget raises.

Related