BoundaryML/baml · error

Environment variable {key} not set

Error message

Environment variable {key} not set

What it means

The GetEnvVar implementation used by ValueExpr::resolve looks up an environment variable and, when it is unset, either returns a "$KEY" placeholder (if fill_missing_env_vars is enabled) or raises this error. It means a required environment variable was not present in the process environment at resolution time.

Source

Thrown at engine/baml-lib/baml-types/src/value_expr.rs:482

pub struct EvaluationContext<'a> {
    env_vars: Option<&'a HashMap<String, String>>,
    fill_missing_env_vars: bool,
}

impl GetEnvVar for EvaluationContext<'_> {
    fn get_env_var(&self, key: &str) -> Result<String> {
        match self
            .env_vars
            .as_ref()
            .and_then(|env_vars| env_vars.get(key))
        {
            Some(v) => Ok(v.to_string()),
            None => {
                if self.fill_missing_env_vars {
                    Ok(format!("${key}"))
                } else {
                    Err(anyhow::anyhow!("Environment variable {key} not set"))
                }
            }
        }
    }

    fn set_allow_missing_env_var(&self, allow: bool) -> Self {
        Self {
            env_vars: self.env_vars,
            fill_missing_env_vars: allow,
        }
    }
}

impl<'a> EvaluationContext<'a> {
    pub fn new(env_vars: &'a HashMap<String, String>, fill_missing_env_vars: bool) -> Self {
        Self {
            env_vars: Some(env_vars),
            fill_missing_env_vars,

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Set the environment variable before running (export KEY=value or add it to .env and load it at startup).
2. Check the variable exists with std::env::var before resolving, and give a clear setup message if absent.
3. Enable fill_missing_env_vars if a "$KEY" placeholder is acceptable for your use case.
4. Document/validate required env vars at application startup instead of at first use.

Example fix

// before
let key = expr.resolve(&env)?;
// after
if std::env::var("MY_KEY").is_err() {
    anyhow::bail!("Set MY_KEY in your environment (see .env.example)");
}
let key = expr.resolve(&env)?;

std::env::var("MY_KEY").map_err(|_| anyhow!("MY_KEY is not set; add it to your environment or .env"))?;

let key = expr.resolve(&env).map_err(|e| anyhow!("missing env var: {}", e))?;

When it happens

Trigger: Calling resolve() on a ValueExpr::EnvVar whose key is missing from the environment and whose resolver has fill_missing_env_vars = false.

Common situations: Deployments where .env files were not loaded (dotenv not initialized), CI/CD secrets not injected, renamed variables after config updates, or running locally without exporting required keys.

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

• Failed to resolve expression {:?} with error: {:?}
• {path}: missing `[package]` table. Add: [package] n
• package '{package_name}' not found in cargo metadata
• Expected a statically defined string, not env variable
• Expected a string, not an array

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