BoundaryML/baml · error · BamlClientError

BamlError: BamlClientError: Something went wrong with the LL

Error message

BamlError: BamlClientError: Something went wrong with the LLM client: {failed.message}

What it means

When from_anyhow_error sees LLMResponse::LLMFailure with code ErrorCode::Other(2), it maps it to 'BamlError: BamlClientError: Something went wrong with the LLM client: <failed.message>'. This is BAML's BamlClientError family: the LLM provider call itself failed (auth, network, bad request, provider-side error).

Source

Thrown at engine/language_client_typescript/src/errors.rs:92

                None
            } else {
                Some(detailed_message.as_str())
            }),
            ExposedError::TimeoutError {
                client_name,
                message,
            } => throw_baml_timeout_error(client_name, message),
        }
    } else if let Some(er) = err.downcast_ref::<ScopeStack>() {
        invalid_argument_error(&format!("{er}"))
    } else if let Some(er) = err.downcast_ref::<LLMResponse>() {
        match er {
            LLMResponse::Success(_) => napi::Error::new(
                napi::Status::GenericFailure,
                format!("BamlError: Unexpected error from BAML: {err}"),
            ),
            LLMResponse::LLMFailure(failed) => match &failed.code {
                baml_runtime::internal::llm_client::ErrorCode::Other(2) => napi::Error::new(
                    napi::Status::GenericFailure,
                    format!(
                        "BamlError: BamlClientError: Something went wrong with the LLM client: {}",
                        failed.message
                    ),
                ),
                baml_runtime::internal::llm_client::ErrorCode::Timeout => {
                    throw_baml_timeout_error(failed.client.as_str(), failed.message.as_str())
                }
                baml_runtime::internal::llm_client::ErrorCode::Other(_)
                | baml_runtime::internal::llm_client::ErrorCode::InvalidAuthentication
                | baml_runtime::internal::llm_client::ErrorCode::NotSupported
                | baml_runtime::internal::llm_client::ErrorCode::RateLimited
                | baml_runtime::internal::llm_client::ErrorCode::ServerError
                | baml_runtime::internal::llm_client::ErrorCode::ServiceUnavailable
                | baml_runtime::internal::llm_client::ErrorCode::UnsupportedResponse(_) => {
                    throw_baml_client_http_error(
                        failed.client.as_str(),

View on GitHub (pinned to bd85ce9dee)

Solutions

Read failed.message / the message suffix for the provider's reason (401 auth, 429 rate limit, model not found).
Verify the provider API key env var is set and valid for the configured client.
Check the client config in .baml (model name, base_url, api_key) for typos.
Add a retry policy to the client in .baml for transient failures, and/or catch BamlClientError in JS to degrade gracefully.

Example fix

// .baml, before
client Gpt4 {
  provider openai
  model gpt-4o-mini
}
// after
client Gpt4 {
  provider openai
  model gpt-4o-mini
  options {
    api_key env.OPENAI_API_KEY
    max_retries 3
  }
}

Defensive patterns

Strategy: retry

Validate before calling

if (!process.env.OPENAI_API_KEY && clientUsesOpenAI) throw new Error('OPENAI_API_KEY not set before BAML call');

Type guard

function isBamlClientError(e: unknown): e is Error {
  return e instanceof Error && e.message.startsWith('BamlError: BamlClientError:');
}

Try / catch

try {
  const res = await b.MyFunction(input);
} catch (e) {
  if (isBamlClientError(e)) {
    if (e.message.includes('429')) await sleep(backoff++ * 1000).then(() => retry());
    else if (e.message.includes('401')) notifyOps('Bad LLM API key');
    else throw e;
  } else throw e;
}

Prevention

Set provider API keys as env vars and assert them at startup.
Add a retry policy (max_retries, backoff) to LLM clients in .baml.
Validate model names and base_url against the provider's current catalog.
Catch BamlClientError at call sites and fall back to another client.

When it happens

Trigger: A b.FunctionName() call whose LLM round-trip failed: invalid API key, exhausted quota/rate limit, unreachable provider, malformed request the provider rejected, or retry strategy exhausted.

Common situations: Missing/rotated OPENAI_API_KEY / ANTHROPIC_API_KEY env vars; wrong model name in the client config; network blocked in CI; provider 4xx/5xx responses after BAML's retry policy gives up.

Related errors

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