What causes "Invalid value for prefix (expected string | null): {e}" in BoundaryML/baml?

Pass a string or null: `output_format(prefix="My prefix:")` or omit `prefix` entirely.

BoundaryML/baml · error · minijinja::Error

SyntaxError

SyntaxError

Error message

Invalid value for prefix (expected string | null): {e}

What it means

The `prefix` kwarg of BAML's `output_format()` must be a string or null. When `kwargs.get::<Option<String>>("prefix")` fails to deserialize the provided value, the filter wraps the minijinja deserialization error in this SyntaxError. It guards the typed options contract of the filter.

Source

Thrown at engine/baml-lib/jinja-runtime/src/output_format/mod.rs:61

        self: &std::sync::Arc<Self>,
        _state: &minijinja::State<'_, '_>,
        args: &[minijinja::value::Value],
    ) -> Result<minijinja::value::Value, minijinja::Error> {
        use minijinja::{value::from_args, Error};

        let (args, kwargs): (&[Value], Kwargs) = from_args(args)?;
        if !args.is_empty() {
            return Err(Error::new(
                ErrorKind::TooManyArguments,
                "output_format() may only be called with named arguments".to_string(),
            ));
        }

        let prefix = if kwargs.has("prefix") {
            match kwargs.get::<Option<String>>("prefix") {
                Ok(prefix) => Some(prefix),
                Err(e) => {
                    return Err(Error::new(
                        ErrorKind::SyntaxError,
                        format!("Invalid value for prefix (expected string | null): {e}"),
                    ))
                }
            }
        } else {
            None
        };

        let or_splitter = if kwargs.has("or_splitter") {
            match kwargs.get::<String>("or_splitter") {
                Ok(prefix) => Some(prefix),
                Err(e) => {
                    return Err(Error::new(
                        ErrorKind::SyntaxError,
                        format!("Invalid value for or_splitter (expected string): {e}"),
                    ))
                }

View on GitHub (pinned to bd85ce9dee)

Solutions

Pass a string or null: `output_format(prefix="My prefix:")` or omit `prefix` entirely.
Coerce numbers/other values to strings before passing, e.g. `prefix=idx | string`.
Verify the interpolated variable actually holds a string in your BAML function/client code.

Example fix

// before
{{ output_format(prefix=42) }}
// after
{{ output_format(prefix="42") }}

Defensive patterns

Strategy: type-guard

Validate before calling

// Before rendering, ensure prefix is string or null
if (prefix !== null && typeof prefix !== "string") throw new Error(`prefix must be string|null, got ${typeof prefix}`);

Type guard

const isStringOrNull = (v) => v === null || v === undefined || typeof v === "string";

Try / catch

try {
  render(prompt);
} catch (e) {
  if (String(e).includes("Invalid value for prefix")) console.error("Fix output_format(prefix=...) to a string or null");
  throw e;
}

Prevention

Coerce dynamic values with the Jinja `| string` filter before passing as prefix.
Omit the kwarg instead of passing other sentinel types.
Type the variable as string|null in the code that builds the template context.

When it happens

Trigger: Calling `output_format(prefix=123)`, `output_format(prefix=["a"])`, `output_format(prefix=true)` or passing any non-string, non-null value for `prefix` in a BAML template.

Common situations: Interpolating a variable of the wrong type into the kwarg (e.g. a number or list from prompt metadata); typos that bind the wrong variable; building kwargs dynamically and losing type guarantees.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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