What causes "expected `true` or `false`, got `{raw}`" in BoundaryML/baml?

Pass the literal lowercase `true` or `false` after `--` for boolean parameters.

expected `true` or `false`, got `{raw}`

Error message

expected `true` or `false`, got `{raw}`

What it means

When a CLI parameter's runtime type is Bool, auto-CLI parses the raw string with an exact match against `true` or `false`. Any other spelling is rejected with this message. This prevents silent coercion of arbitrary strings into booleans.

Source

Thrown at baml_language/crates/baml_exec/src/auto_cli.rs:64

        RuntimeTy::Int { .. } => {
            let v: i64 = raw
                .parse()
                .with_context(|| format!("expected integer, got `{raw}`"))?;
            Ok(BexExternalValue::Int(v))
        }

        RuntimeTy::Float { .. } => {
            let v: f64 = raw
                .parse()
                .with_context(|| format!("expected float, got `{raw}`"))?;
            Ok(BexExternalValue::Float(v))
        }

        RuntimeTy::Bool { .. } => match raw {
            "true" => Ok(BexExternalValue::Bool(true)),
            "false" => Ok(BexExternalValue::Bool(false)),
            _ => anyhow::bail!("expected `true` or `false`, got `{raw}`"),
        },

        RuntimeTy::Null { .. } => {
            if raw == "null" {
                Ok(BexExternalValue::Null)
            } else {
                anyhow::bail!("expected `null`, got `{raw}`")
            }
        }

        // `T?` is `T | null`: accept the literal `null`, else parse the value
        // against the non-null inner type.
        RuntimeTy::Union(..) if ty.is_nullable_union() => {
            if raw == "null" {
                Ok(BexExternalValue::Null)
            } else {
                parse_cli_value(raw, &ty.strip_null())
            }

View on GitHub (pinned to bd85ce9dee)

Solutions

Pass the literal lowercase `true` or `false` after `--` for boolean parameters.
Alternatively deliver the value via `--json-args '{"<param>": true}'` so JSON parsing handles it.
Check `baml run <target> --help` for the parameter's declared type.

Example fix

// before
baml run myFunc -- --flag 1

// after
baml run myFunc -- --flag true

Defensive patterns

Strategy: validation

Validate before calling

fn valid_cli_bool(raw: &str) -> bool { matches!(raw, "true" | "false") }

Type guard

fn as_cli_bool(raw: &str) -> Option<bool> {
    match raw { "true" => Some(true), "false" => Some(false), _ => None }
}

Try / catch

match result {
    Ok(v) => use(v),
    Err(e) if e.to_string().contains("expected `true` or `false`") => {
        eprintln!("boolean flags accept only lowercase true/false: {e}");
    }
    Err(e) => return Err(e),
}

Prevention

Always quote boolean flag values in shell scripts
Use lowercase true/false, never 1/0 or True/False
Prefer --json-args for programmatic invocation

When it happens

Trigger: Calling `parse_cli_value` for a `RuntimeTy::Bool` parameter with a raw value other than exactly `true` or `false` (e.g. `True`, `1`, `yes`, `TRUE`); typically via `baml run -- <param> <value>`.

Common situations: Passing shell-style booleans like `1`/`0` or `yes`/`no`, capitalizing `True`/`False` out of habit from Python, or quoting values oddly in shell scripts.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

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