BoundaryML/baml · error

LLM client '{client_name}' requires environment variable '{k

Error message

LLM client '{client_name}' requires environment variable '{key}' to be set but it is not

What it means

When loading clients, BAML collects the environment variables that each LLM client's provider config requires (declared via env_variable or referenced provider config). If a required variable is absent from the environment and fail_on_missing_required_env_vars is true, the runtime bails with this error naming the client and the missing key. It prevents constructing API clients that would inevitably fail at request time with an auth error.

Source

Thrown at engine/baml-runtime/src/lib.rs:1951

                // env vars because the proxy server is likely to provide them.
                let fail_on_missing_required_env_vars = !ctx.is_modular_api()
                    && !uses_proxy_server
                    && !matches!(
                        walker.item.elem.provider,
                        internal_llm_client::ClientProvider::AwsBedrock
                            | internal_llm_client::ClientProvider::Vertex
                    );

                for key in walker.required_env_vars() {
                    if let Some(value) = ctx.env_vars().get(&key) {
                        if fail_on_missing_required_env_vars && value.trim().is_empty() {
                            baml_log::warn!(
                                "Required environment variable '{key}' for client '{client_name}' is set but is empty: {key}='{value}'"
                            );
                        }
                        required_env_vars.insert(key, value.to_owned());
                    } else if fail_on_missing_required_env_vars {
                        anyhow::bail!(
                            "LLM client '{client_name}' requires environment variable '{key}' to be set but it is not"
                        );
                    }
                }

                // Also include BOUNDARY_* env vars if they exist, for tracing/telemetry
                if let Some(boundary_api_key) = ctx.env_vars().get("BOUNDARY_API_KEY") {
                    required_env_vars
                        .insert("BOUNDARY_API_KEY".to_string(), boundary_api_key.to_owned());
                }
                if let Some(boundary_api_url) = ctx.env_vars().get("BOUNDARY_API_URL") {
                    required_env_vars
                        .insert("BOUNDARY_API_URL".to_string(), boundary_api_url.to_owned());
                }

                clients.insert(
                    client_name.into(),
                    runtime::CachedClient::new(new_client.clone(), required_env_vars),

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Export the required environment variable (e.g. `export OPENAI_API_KEY=sk-...`) or add it to your .env file before starting the app
2. Check the variable name in generators.baml matches the actual env var exactly (case-sensitive)
3. In CI/deployment, add the secret to the environment/secret manager (GitHub Actions secrets, Docker env, Lambda env vars)
4. Restart the dev server/shell after setting the variable so it's picked up

Example fix

// before
BAML_SECRET_OPENAI_API_KEY= sk-  (missing in shell)

// after
# .env
OPENAI_API_KEY=sk-...
# then
export $(grep -v '^#' .env | xargs)

const required = ['OPENAI_API_KEY']; // keys referenced in generators.baml
const missing = required.filter((k) => !process.env[k]);
if (missing.length) throw new Error(`Missing env vars before loading BAML: ${missing.join(', ')}`);

try {
  await bamlRuntime.loadSrc({ bamlSrc });
} catch (e) {
  const m = /requires environment variable '([^']+)'/i.exec(e.message);
  if (m) throw new Error(`Set ${m[1]} in your environment (check .env and deployment secrets)`);
  throw e;
}

When it happens

Trigger: Calling BamlRuntime load / client setup (e.g. `baml-cli dev`, runtime.load_src, LoadSrcArgs) where a client like `provider "openai" { api_key env.OPENAI_API_KEY }` references an env var that is unset, while fail_on_missing_required_env_vars is enabled.

Common situations: Deploying to a server/CI where the .env file isn't copied; forgetting to export the key in the shell; typo in the variable name between generators.baml and the environment; secrets not injected into a container/serverless runtime.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Configuration error: {0}
• options.project_id is required when using API key auth with
• Invalid client property. Should have been a fallback propert
• Unsupported strategy provider: {}
• Unsupported strategy provider: {}. Available ones are: {}

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