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

Error message

missing required argument `--{name}` (type: {ty}).
pass it after `--`: `... -- --{name} <value>`

What it means

A required parameter of primitive type was not supplied. Auto-CLI points at the legacy syntax: pass the value as a flag after `--` on the command line. The primitive check (`is_auto_cli_primitive`) decides which hint you get - primitives get the `--name <value>` hint rather than the JSON one.

Source

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

            Some(RawArg::JsonText(s)) => {
                let value = deserialize_via_baml_json(engine, &s, ty, helper_context)
                    .await
                    .with_context(|| format!("parameter `--{name}`"))?;
                ordered.push(BexCallArg::Provided(Box::new(value)));
            }
            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(", ")

View on GitHub (pinned to bd85ce9dee)

Solutions

Add the missing flag after `--`: `baml run <target> -- --<name> <value>`.
Alternatively supply it via `--json-args '{"<name>": ...}'` - JSON args work for primitives too.
Check the target's signature or `--help` output to confirm the parameter name and type.

Example fix

// before
baml run greet

// after
baml run greet -- --name "world"

Defensive patterns

Strategy: validation

Validate before calling

// check required primitive params are present before dispatch
for (name, ty, required) in signature.params {
    if required && is_primitive(ty) && !cli_args.contains_key(name) {
        eprintln!("missing --{name} ({ty})");
    }
}

Try / catch

match result {
    Err(e) if e.to_string().contains("missing required argument") => {
        eprintln!("supply the flag after --: `... -- --name <value>`");
    }
    other => other,
}

Prevention

Consult `baml run <target> --help` for the full required-flag list
Update call scripts when a function gains new required parameters
Spell flag names exactly as declared (kebab-case as shown in help)

When it happens

Trigger: Dispatching a target whose signature has a required primitive parameter (string/int/float/bool) that is absent from both the CLI argv after `--` and any `--json-args`.

Common situations: Omitting a mandatory argument, misspelling the flag name so it doesn't match a required param, or calling a function whose signature recently gained a new required parameter.

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