missing required argument `{name}` (type: {ty}). pass it via

Error message

missing required argument `{name}` (type: {ty}).
pass it via `--json-args '{{"{name}": ...}}'` (or `--json-args @file` / `--json-args -` for stdin).

What it means

Same missing-required-argument condition as the primitive variant, but for non-primitive types (media, objects, lists, etc.). Because those values can't be passed as raw shell flags, the error directs you to `--json-args`, including the `@file` and stdin (`-`) forms.

Source

Thrown at baml_language/crates/baml_exec/src/dispatch.rs:257

            }
            None if has_default => ordered.push(BexCallArg::OmittedDefault),
            None => {
                // Primitive params should have been caught by clap as
                // required flags — if we get here, either the caller
                // (test) bypassed clap or the param is non-primitive
                // (class/list/map/union/etc.), which has no `--name`
                // flag and is only deliverable via `--json-args`. Point
                // at `--json-args` for non-primitives so the hint
                // matches the help-block guidance; keep the legacy
                // `--name`-after-`--` hint for primitives so test
                // expectations and bare engine callers stay friendly.
                if crate::is_auto_cli_primitive(ty) {
                    anyhow::bail!(
                        "missing required argument `--{name}` (type: {ty}).\n\
                         pass it after `--`: `... -- --{name} <value>`"
                    );
                }
                anyhow::bail!(
                    "missing required argument `{name}` (type: {ty}).\n\
                     pass it via `--json-args '{{\"{name}\": ...}}'` \
                     (or `--json-args @file` / `--json-args -` for stdin)."
                );
            }
        }
    }

    if !merged.is_empty() {
        let unknown: Vec<&str> = merged.keys().map(String::as_str).collect();
        crate::print_warning(format_args!(
            "unknown argument(s) ignored: {}",
            unknown.join(", ")
        ));
    }

    Ok(ordered)
}

View on GitHub (pinned to bd85ce9dee)

Solutions

Pass the parameter via `--json-args '{"<name>": ...}'`.
Use `--json-args @file` for large payloads or `--json-args -` to pipe from stdin.
Make the parameter optional in the function signature if it genuinely has no required value.

Example fix

// before
baml run analyze -- --json-args '{}'

// after
baml run analyze -- --json-args '{"image": "./cat.png", "options": {"mode": "fast"}}'

Defensive patterns

Strategy: validation

Validate before calling

for (name, ty, required) in signature.params {
    if required && !is_primitive(ty) && !json_args_keys.contains(name) {
        eprintln!("supply {name} ({ty}) via --json-args");
    }
}

Try / catch

match result {
    Err(e) if e.to_string().contains("pass it via `--json-args`") => {
        eprintln!("add the parameter to --json-args or @file/stdin");
    }
    other => other,
}

Prevention

Build complete --json-args objects covering all required non-primitive params
Use --json-args @file to keep complex payloads maintainable
Review entry-point signatures when tests fail with missing-argument errors

When it happens

Trigger: Dispatching a target with a required non-primitive parameter that was not provided in `--json-args` (inline, `@file`, or `-`); `build_args_from_signature_with_context` bails after failing the `is_auto_cli_primitive` check.

Common situations: Forgetting a structured/media parameter entirely, supplying only the primitive ones, or passing a non-primitive as a positional flag (which would instead hit the can't-be-passed error) rather than via JSON.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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