What causes "base_url is required" in BoundaryML/baml?

Add `base_url "https://your-endpoint/v1"` to the client options.

base_url is required

Error message

base_url is required

What it means

The openai client variant being resolved (a generic/base-url-driven variant) requires a `base_url` option. After resolving the configured value, a None base_url aborts with "base_url is required" since these variants have no default endpoint.

Source

Thrown at engine/baml-lib/llm-client/src/clients/openai.rs:189

        ctx: &impl GetEnvVar,
    ) -> Result<ResolvedOpenAI> {
        let base_url = self
            .base_url
            .as_ref()
            .map(|url| match url {
                either::Either::Left(url) => url.resolve(ctx),
                either::Either::Right((resource_name, deployment_id)) => {
                    let resource_name = resource_name.resolve(ctx)?;
                    let deployment_id = deployment_id.resolve(ctx)?;
                    Ok(format!(
                        "https://{resource_name}.openai.azure.com/openai/deployments/{deployment_id}"
                    ))
                }
            })
            .transpose()?;

        let Some(base_url) = base_url else {
            return Err(anyhow::anyhow!("base_url is required"));
        };

        let api_key = self
            .api_key
            .as_ref()
            .map(|key| key.resolve_api_key(ctx))
            .transpose()?;

        let role_selection = self.role_selection.resolve(ctx)?;

        let headers = self
            .headers
            .iter()
            .map(|(k, v)| Ok((k.clone(), v.resolve(ctx)?)))
            .collect::<Result<IndexMap<_, _>>>()?;

        let properties = {
            let mut properties = self

View on GitHub (pinned to bd85ce9dee)

Solutions

Add `base_url "https://your-endpoint/v1"` to the client options.
Ensure the env var referenced in base_url is exported and non-empty.
If you intended the standard OpenAI API, switch to provider "openai" which has a default base URL.

Example fix

// before
client "Local" {
  provider "openai-generic"
  options { model "llama3" }
}
// after
client "Local" {
  provider "openai-generic"
  options {
    model "llama3"
    base_url "http://localhost:11434/v1"
  }
}

Defensive patterns

Strategy: validation

Validate before calling

if cfg.base_url.is_none() && requires_base_url(cfg.provider) { panic!("base_url is required for this provider variant"); }

Prevention

Always set base_url for openai-generic/openrouter/ollama-style clients.
Confirm interpolated env vars (e.g. ${BASE_URL}) are exported before running.
Use provider "openai" if you want the default OpenAI endpoint instead of generic.

When it happens

Trigger: Using an openai-generic/openai-compatible provider without setting `base_url`; base_url expression resolving to None (missing env var); constructing OpenAi client struct programmatically without base_url.

Common situations: Pointing at a self-hosted OpenAI-compatible server (vLLM, LM Studio) and forgetting base_url; env-var interpolation failing so base_url resolves empty/None; using the generic variant instead of the built-in openai provider that has a default URL.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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