BoundaryML/baml · error · ExposedError::TimeoutError

LLM client "{client_name}" timed out: {message}

Error message

LLM client "{client_name}" timed out: {message}

What it means

BAML's orchestrator wraps LLM provider failures into typed ExposedError variants while executing a retry strategy. When a provider returns an LLMResponse::LLMFailure with ErrorCode::Timeout, the node converts it into ExposedError::TimeoutError carrying the client name and provider message. This means the configured LLM client did not answer within its timeout budget before BAML tried the next node in the strategy.

Source

Thrown at engine/baml-runtime/src/internal/llm_client/orchestrator/call.rs:137

                                    message,
                                    finish_reason: s.metadata.finish_reason.clone(),
                                }
                            )))
                        } else {
                            Some(parse_fn(&s.content))
                        }
                    }
                    LLMResponse::LLMFailure(LLMErrorResponse {
                        code,
                        client,
                        message,
                        raw_response,
                        ..
                    }) => {
                        match code {
                            // Timeout error
                            crate::internal::llm_client::ErrorCode::Timeout => {
                                Some(Err(anyhow::anyhow!(
                                    crate::errors::ExposedError::TimeoutError {
                                        client_name: client.clone(),
                                        message: message.clone(),
                                    }
                                )))
                            }
                            // This is some internal BAML error, so handle it like any other error
                            crate::internal::llm_client::ErrorCode::Other(2) => {
                                Some(Err(anyhow::anyhow!(message.clone())))
                            }
                            _ => Some(Err(anyhow::anyhow!(
                                crate::errors::ExposedError::ClientHttpError {
                                    client_name: client.clone(),
                                    message: message.clone(),
                                    status_code: code.clone(),
                                    detailed_message: message.clone(),
                                    raw_response: raw_response.clone(),
                                }

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Increase the client's timeout in clients.baml, e.g. client<TimedChat> { provider openai options { model gpt-4o timeout 120s } }.
2. Add a retry strategy with multiple clients so the orchestrator fails over to a faster/healthier provider when one times out.
3. Reduce prompt size or max_tokens / enable streaming so the response completes within the budget.
4. Check provider status pages and network connectivity (proxy, VPN) if timeouts are new.
5. Catch ExposedError::TimeoutError in the caller and apply backoff before retrying.

Example fix

// before (clients.baml)
client<TimedChat> {
  provider openai
  options { model gpt-4o timeout 10s }
}
// after
client<TimedChat> {
  provider openai
  options { model gpt-4o timeout 120s }
}
retry_policy LongRetry {
  max_retries 3
  strategy { type exponential_backoff }
}

// clients.baml sanity check before invoking
// ensure client options include a timeout and a retry policy exists
// client<"gpt4"> { provider openai options { timeout 120s } }

// python
from baml_py import BamlError, TimeoutError
try:
    result = b.ExtractDocs(text)
except TimeoutError as e:
    log.warning("LLM client timed out, retrying: %s", e)
    result = b.ExtractDocs(text)  # or route to a fallback client
except BamlError as e:
    handle_other_baml_error(e)

When it happens

Trigger: Calling any BAML function (baml.Functions.MyFunc or b.Function) whose retry strategy invokes an LLM client that returns ErrorCode::Timeout - e.g. the HTTP request to the model provider exceeds the client's timeout_ms in clients.baml, or the provider library itself reports a timeout.

Common situations: Low timeout_ms values in clients.baml for slow models (large prompts, long generations, reasoning models); provider outages or rate-limit-induced slowness; network latency from a distant region or through a proxy; streaming disabled so the whole response must arrive before the deadline.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• ExposedError::TimeoutError { client_name, message }
• BamlError: BamlClientError: BamlTimeoutError: {message}
• timeout: {message}
• {self}\n\nDetailed message: {detailed_message}
• {}

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/0c31a76ba5886a91. Report an issue: GitHub.