What causes "expected `null`, got `{raw}`" in BoundaryML/baml?

Pass the exact lowercase string `null` for a null-valued parameter.

expected `null`, got `{raw}`

Error message

expected `null`, got `{raw}`

What it means

For a parameter whose runtime type is Null, auto-CLI only accepts the exact literal string `null`. Any other raw value fails with this error. Nullable unions (`T?`) are handled separately: `null` short-circuits, otherwise the inner type parses the value.

Source

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

        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())
            }
        }

        RuntimeTy::Enum(type_name, _) => Ok(BexExternalValue::Variant {
            enum_name: type_name.display_name().to_string(),
            variant_name: raw.to_string(),
        }),

View on GitHub (pinned to bd85ce9dee)

Solutions

Pass the exact lowercase string `null` for a null-valued parameter.
Use `--json-args '{"<param>": null}'` for JSON-native null.
If the parameter should hold a real value, fix the function signature - a bare Null-typed param only accepts `null`.

Example fix

// before
baml run myFunc -- --opt NULL

// after
baml run myFunc -- --opt null

Defensive patterns

Strategy: validation

Validate before calling

fn valid_cli_null(raw: &str) -> bool { raw == "null" }

Type guard

fn as_cli_null(raw: &str) -> Option<()> { if raw == "null" { Some(()) } else { None } }

Try / catch

match result {
    Ok(v) => use(v),
    Err(e) if e.to_string().contains("expected `null`, got") => {
        eprintln!("use the literal lowercase string null: {e}");
    }
    Err(e) => return Err(e),
}

Prevention

Spell null exactly as lowercase `null` (not NULL/None/nil)
Prefer omitting the flag or using --json-args null for nullable params
Check the parameter's declared type via --help

When it happens

Trigger: Passing a non-`null` string to a CLI parameter typed as Null; `parse_cli_value` bails when `raw != "null"` for `RuntimeTy::Null`.

Common situations: Typos like `None`, `nil`, `NULL`, or `none` when trying to pass an explicit null from the command line.

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/ad93041bf9520112. Report an issue: GitHub.